TypeScript SDK

1git clone https://github.com/MNMX-labs/mnmx.git
2cd mnmx
3npm install
4npm run build

1import { MnmxRouter } from '@mnmx/core';
2
3const router = new MnmxRouter({
4  strategy: 'minimax',
5  slippageTolerance: 0.5,
6  timeout: 30_000,
7  bridges: ['wormhole', 'debridge', 'layerzero', 'allbridge'],
8  maxHops: 3,
9});

1const route = await router.findRoute({
2  from: { chain: 'ethereum', token: 'ETH', amount: '1.0' },
3  to:   { chain: 'solana',   token: 'SOL' },
4});
5
6console.log(route.path);              // RouteHop[] — ordered sequence of hops
7console.log(route.expectedOutput);    // "14.32" — best-case output
8console.log(route.guaranteedMinimum); // "13.85" — minimax (worst-case) output
9console.log(route.estimatedTime);     // 180 — seconds
10console.log(route.totalFees);         // "0.0045" — total fees in ETH equivalent
11console.log(route.minimaxScore);      // 0.847 — normalized score [0,1]
12console.log(route.strategy);          // "minimax"

1const routes = await router.findAllRoutes({
2  from: { chain: 'ethereum', token: 'ETH', amount: '1.0' },
3  to:   { chain: 'solana',   token: 'SOL' },
4});
5
6// Routes are sorted by minimax score (highest first)
7for (const route of routes) {
8  console.log(`Route: ${route.path.map(h => h.provider).join(' → ')}`);
9  console.log(`  Expected:   ${route.expectedOutput} SOL`);
10  console.log(`  Guaranteed: ${route.guaranteedMinimum} SOL`);
11  console.log(`  Fees:       ${route.totalFees}`);
12  console.log(`  Time:       ${route.estimatedTime}s`);
13  console.log(`  Score:      ${route.minimaxScore.toFixed(4)}`);
14  console.log();
15}

1const result = await router.execute(route, {
2  signer: walletSigner,
3  onProgress: (step) => {
4    console.log(`Step ${step.index + 1}/${step.total}: ${step.hop.provider}`);
5    console.log(`  Status: ${step.status}`);
6    if (step.txHash) console.log(`  TX: ${step.txHash}`);
7    if (step.output) console.log(`  Output: ${step.output}`);
8  },
9  autoRetry: true,
10  maxRetries: 2,
11  confirmations: {
12    ethereum: 2,    // Wait for 2 confirmations on Ethereum
13    solana: 1,      // Solana is single-slot finality
14    arbitrum: 1,
15  },
16});
17
18console.log(result.execId);        // "exec_a7f3b2c1..."
19console.log(result.status);        // "completed" | "failed" | "partial"
20console.log(result.actualOutput);  // "14.12" — actual SOL received
21console.log(result.totalTime);     // 245 — actual seconds taken
22console.log(result.txHashes);      // ["0xabc...", "5Yfg...", "0xdef..."]

1const status = await router.getStatus('exec_a7f3b2c1...');
2
3console.log(status.state);         // "in_progress" | "completed" | "failed"
4console.log(status.currentStep);   // 2 — which hop is currently executing
5console.log(status.totalSteps);    // 3
6console.log(status.fundsLocation); // { chain: "solana", token: "USDC", amount: "3247.82" }
7console.log(status.elapsedTime);   // 134 — seconds since execution started
8console.log(status.steps);         // ExecStep[] — detailed per-hop status

1interface Route {
2  id: string;                     // Unique route identifier
3  path: RouteHop[];               // Ordered sequence of hops
4  expectedOutput: string;         // Best-case output amount
5  guaranteedMinimum: string;      // Minimax (worst-case) output
6  totalFees: string;              // Total fees across all hops
7  totalFeesUSD: string;           // Total fees in USD
8  estimatedTime: number;          // Expected transfer time (seconds)
9  minimaxScore: number;           // Combined minimax evaluation score [0,1]
10  strategy: Strategy;             // Strategy used for this route
11  quotedAt: number;               // Timestamp when quote was generated
12  expiresAt: number;              // Timestamp when quote expires
13  warnings: RouteWarning[];       // Any warnings about this route
14
15  // Breakdown of adversarial penalties
16  penalties: {
17    slippage: string;
18    gasSurge: string;
19    mev: string;
20    priceMovement: string;
21    bridgeRisk: string;
22  };
23}
24
25interface RouteHop {
26  type: 'swap' | 'bridge';
27  from: { chain: string; token: string; amount: string };
28  to: { chain: string; token: string; amount: string };
29  provider: string;               // DEX or bridge name
30  fee: string;                    // Fee for this hop
31  feeUSD: string;                 // Fee in USD
32  estimatedTime: number;          // Time for this hop (seconds)
33  priceImpact: number;            // Slippage/price impact (0.01 = 1%)
34  metadata: Record<string, unknown>; // Provider-specific data
35}
36
37interface RouteWarning {
38  code: string;                   // Warning code (e.g., "LOW_LIQUIDITY")
39  message: string;                // Human-readable warning
40  severity: 'info' | 'warning' | 'critical';
41  hop?: number;                   // Which hop this warning applies to
42}

1interface RouteParams {
2  from: {
3    chain: string;                // Source chain (e.g., 'ethereum')
4    token: string;                // Source token (e.g., 'ETH')
5    amount: string;               // Amount to transfer (human-readable)
6  };
7  to: {
8    chain: string;                // Destination chain (e.g., 'solana')
9    token: string;                // Destination token (e.g., 'SOL')
10  };
11  options?: RouteOptions;
12}
13
14interface RouteOptions {
15  excludeBridges?: string[];      // Bridges to exclude
16  excludeChains?: string[];       // Intermediate chains to exclude
17  excludeProviders?: string[];    // Specific providers (DEX or bridge) to exclude
18  deadline?: number;              // Max acceptable transfer time (seconds)
19  preferredBridge?: string;       // Prefer this bridge (still evaluated by minimax)
20  minOutput?: string;             // Reject routes with guaranteed minimum below this
21  includeGasEstimate?: boolean;   // Include per-hop gas estimates (default: true)
22}

1interface ExecOpts {
2  signer: Signer;                   // Wallet signer for transactions
3  onProgress?: (step: ExecStep) => void;  // Progress callback
4  autoRetry?: boolean;              // Retry failed steps (default: true)
5  maxRetries?: number;              // Max retry attempts per hop (default: 2)
6  confirmations?: Record<string, number>; // Required confirmations per chain
7  gasLimitBuffer?: number;          // Gas limit buffer multiplier (default: 1.15)
8  dryRun?: boolean;                 // Simulate without submitting txs (default: false)
9}
10
11interface ExecResult {
12  execId: string;                   // Unique execution ID
13  status: 'completed' | 'failed' | 'partial';
14  actualOutput: string;             // Actual amount received
15  totalTime: number;                // Actual total time (seconds)
16  steps: ExecStep[];                // Detailed step results
17  txHashes: string[];               // Transaction hashes per chain
18  totalGasUsed: string;             // Total gas cost in USD
19  deviationFromQuote: number;       // % deviation from quoted output
20  meetsGuarantee: boolean;          // actualOutput >= guaranteedMinimum
21  fundsLocation: FundsLocation;     // Where funds currently are
22}
23
24interface ExecStep {
25  index: number;                    // Step index (0-based)
26  total: number;                    // Total number of steps
27  hop: RouteHop;                    // The hop being executed
28  status: 'pending' | 'simulated' | 'submitted' | 'confirmed' | 'completed' | 'failed' | 'retrying';
29  txHash?: string;                  // Transaction hash (once submitted)
30  output?: string;                  // Actual output amount
31  gasUsed?: string;                 // Gas used for this step
32  error?: string;                   // Error message (if failed)
33  startedAt?: number;               // Timestamp when step started
34  completedAt?: number;             // Timestamp when step completed
35}
36
37interface FundsLocation {
38  chain: string;                    // Which chain funds are on
39  token: string;                    // Which token
40  amount: string;                   // How much
41  status: 'wallet' | 'locked' | 'in_transit' | 'claimable';
42  txHash?: string;                  // Relevant transaction hash
43}

1interface ChainInfo {
2  id: string;                       // Internal chain ID (e.g., 'ethereum')
3  name: string;                     // Display name (e.g., 'Ethereum')
4  chainId: number;                  // EVM chain ID (e.g., 1)
5  type: 'evm' | 'solana' | 'cosmos' | 'move';
6  nativeToken: string;              // Native gas token (e.g., 'ETH')
7  blockTime: number;                // Average block time (seconds)
8  finality: number;                 // Blocks to finality
9  bridges: string[];                // Bridges available on this chain
10  explorerUrl: string;              // Block explorer URL
11}
12
13interface TokenInfo {
14  symbol: string;                   // Token symbol (e.g., 'USDC')
15  name: string;                     // Full name (e.g., 'USD Coin')
16  address: string;                  // Contract address (or 'native')
17  decimals: number;                 // Token decimals
18  chain: string;                    // Which chain this token is on
19  bridgeable: boolean;              // Can be bridged directly
20  bridges: string[];                // Which bridges support this token
21  logoUrl?: string;                 // Token logo URL
22}
23
24// Usage
25const chains = await router.getSupportedChains();
26const tokens = await router.getSupportedTokens('ethereum');
27
28console.log(chains.map(c => c.name));
29// ['Ethereum', 'Solana', 'Arbitrum', 'Base', 'Polygon', ...]
30
31console.log(tokens.filter(t => t.bridgeable).map(t => t.symbol));
32// ['ETH', 'USDC', 'USDT', 'WBTC', 'DAI', ...]

1interface GasEstimate {
2  totalUSD: string;                 // Total gas cost across all chains
3  perHop: GasHopEstimate[];         // Gas cost breakdown per hop
4  nativeTokenCosts: Record<string, string>; // Cost in native token per chain
5}
6
7interface GasHopEstimate {
8  chain: string;
9  gasLimit: string;                 // Estimated gas units
10  gasPrice: string;                 // Current gas price (wei or lamports)
11  costUSD: string;                  // Cost in USD
12  costNative: string;               // Cost in native token
13  type: 'approve' | 'swap' | 'bridge_initiate' | 'bridge_redeem';
14}
15
16// Usage
17const gasEstimate = await router.estimateGas(route);
18console.log(`Total gas: $${gasEstimate.totalUSD}`);
19for (const hop of gasEstimate.perHop) {
20  console.log(`  ${hop.chain} (${hop.type}): $${hop.costUSD}`);
21}

1interface Quote {
2  expectedOutput: string;           // Estimated output amount
3  guaranteedMinimum: string;        // Minimax worst-case output
4  totalFeesUSD: string;             // Estimated total fees
5  estimatedTime: number;            // Estimated transfer time (seconds)
6  bridgeUsed: string;               // Primary bridge in the route
7  hops: number;                     // Number of hops
8  quotedAt: number;                 // Quote timestamp
9  expiresAt: number;                // Quote expiration
10}
11
12// Usage — returns in 200-500ms (uses cached state)
13const quote = await router.getQuote({
14  from: { chain: 'ethereum', token: 'USDC', amount: '5000' },
15  to:   { chain: 'solana',   token: 'USDC' },
16});
17
18console.log(`You'll receive ~${quote.expectedOutput} USDC`);
19console.log(`Minimum guaranteed: ${quote.guaranteedMinimum} USDC`);
20console.log(`Fees: $${quote.totalFeesUSD}`);
21console.log(`Time: ~${quote.estimatedTime}s`);

1interface BridgeAdapter {
2  name: string;
3  supportedChains: Chain[];
4
5  getQuote(params: QuoteParams): Promise<BridgeQuote>;
6  execute(quote: BridgeQuote, signer: Signer): Promise<BridgeResult>;
7  getStatus(txHash: string): Promise<BridgeStatus>;
8  getHealth(): Promise<BridgeHealth>;
9  getLiquidity(chain: string, token: string): Promise<LiquidityInfo>;
10  getSupportedPairs(): Promise<ChainPair[]>;
11  getMetrics(): Promise<BridgeMetrics>;
12}
13
14interface BridgeQuote {
15  bridge: string;
16  inputAmount: string;
17  outputAmount: string;
18  fee: string;
19  estimatedTime: number;            // seconds
20  liquidityDepth: string;           // available liquidity
21  expiresAt: number;                // quote expiration timestamp
22  metadata: Record<string, unknown>;
23}
24
25interface BridgeResult {
26  bridge: string;
27  sourceTxHash: string;
28  destinationTxHash: string;
29  actualOutput: string;
30  actualTime: number;               // milliseconds
31}
32
33interface BridgeStatus {
34  state: 'pending' | 'in_transit' | 'confirming' | 'completed' | 'failed';
35  sourceTxConfirmed: boolean;
36  destinationTxHash?: string;
37  estimatedCompletion?: number;     // timestamp
38  error?: string;
39}
40
41interface BridgeHealth {
42  online: boolean;
43  congestion: 'low' | 'medium' | 'high';
44  recentSuccessRate: number;        // 0.0-1.0
45  medianConfirmTime: number;        // seconds
46  pendingTransfers: number;
47}
48
49interface LiquidityInfo {
50  available: string;                // Available liquidity
51  total: string;                    // Total pool size
52  utilization: number;              // Percentage (0-100)
53}
54
55interface BridgeMetrics {
56  totalTransfers24h: number;
57  totalVolume24h: string;           // USD
58  avgConfirmTime: number;           // seconds
59  p95ConfirmTime: number;           // seconds
60  successRate: number;              // 0.0-1.0
61}

1// EVM signer (ethers.js compatible)
2interface EvmSigner {
3  getAddress(): Promise<string>;
4  signTransaction(tx: TransactionRequest): Promise<string>;
5  sendTransaction(tx: TransactionRequest): Promise<TransactionResponse>;
6  getChainId(): Promise<number>;
7}
8
9// Solana signer (web3.js compatible)
10interface SolanaSigner {
11  publicKey: PublicKey;
12  signTransaction(tx: Transaction): Promise<Transaction>;
13  signAllTransactions(txs: Transaction[]): Promise<Transaction[]>;
14}
15
16// Multi-chain signer wrapper
17interface MultiChainSigner {
18  evm: Record<string, EvmSigner>;    // chainId → signer
19  solana?: SolanaSigner;
20
21  getSigner(chain: string): EvmSigner | SolanaSigner;
22}
23
24// Usage with ethers.js
25import { ethers } from 'ethers';
26
27const provider = new ethers.BrowserProvider(window.ethereum);
28const signer = await provider.getSigner();
29
30const result = await router.execute(route, { signer });
31
32// Usage with multi-chain signer
33const multiSigner: MultiChainSigner = {
34  evm: {
35    ethereum: ethSigner,
36    arbitrum: arbSigner,
37  },
38  solana: solSigner,
39  getSigner(chain) {
40    if (chain === 'solana') return this.solana!;
41    return this.evm[chain];
42  },
43};
44
45const result = await router.execute(route, { signer: multiSigner });

1// Subscribe to router events
2router.on('route:found', (event) => {
3  console.log(`Found ${event.routeCount} routes in ${event.quoteTime}ms`);
4  console.log(`Best: ${event.bestRoute.minimaxScore.toFixed(4)}`);
5});
6
7router.on('route:executing', (event) => {
8  console.log(`Executing route ${event.execId}`);
9});
10
11router.on('hop:started', (event) => {
12  console.log(`Hop ${event.index}: ${event.provider} started`);
13});
14
15router.on('hop:completed', (event) => {
16  console.log(`Hop ${event.index}: ${event.provider} completed. Output: ${event.output}`);
17});
18
19router.on('hop:failed', (event) => {
20  console.log(`Hop ${event.index}: ${event.provider} failed. Error: ${event.error}`);
21});
22
23router.on('bridge:health_changed', (event) => {
24  console.log(`Bridge ${event.bridge}: ${event.oldStatus} → ${event.newStatus}`);
25});
26
27router.on('execution:completed', (event) => {
28  console.log(`Execution ${event.execId} completed. Output: ${event.actualOutput}`);
29});
30
31// Remove listener
32router.off('route:found', handler);

1import {
2  NoRouteFoundError,
3  SlippageExceededError,
4  BridgeTimeoutError,
5  ExecutionFailedError,
6  QuoteExpiredError,
7} from '@mnmx/core';
8
9try {
10  const route = await router.findRoute(params);
11  const result = await router.execute(route, { signer });
12} catch (error) {
13  if (error instanceof NoRouteFoundError) {
14    console.error(`No route: ${error.reason}`);
15    console.error(`Supported pairs: ${error.availablePairs.join(', ')}`);
16  } else if (error instanceof SlippageExceededError) {
17    console.error(`Slippage ${error.actualSlippage}% exceeded tolerance ${error.tolerance}%`);
18    console.error(`Hop: ${error.hop.provider} on ${error.hop.from.chain}`);
19  } else if (error instanceof BridgeTimeoutError) {
20    console.error(`Bridge ${error.bridge} timed out after ${error.elapsed}ms`);
21    console.error(`Source TX: ${error.sourceTxHash}`);
22    console.error(`Check bridge explorer for VAA/attestation status`);
23  } else if (error instanceof QuoteExpiredError) {
24    console.error(`Quote expired ${error.expiredAgo}ms ago. Re-fetching...`);
25    const newRoute = await router.findRoute(params);
26  } else if (error instanceof ExecutionFailedError) {
27    console.error(`Execution failed at step ${error.step}: ${error.message}`);
28    console.error(`Funds location: ${JSON.stringify(error.fundsLocation)}`);
29  }
30}

1// router.findRoute() response for 1 ETH → SOL
2{
3  id: "route_7f3a2b1c",
4  path: [
5    {
6      type: "swap",
7      from: { chain: "ethereum", token: "ETH", amount: "1.0" },
8      to: { chain: "ethereum", token: "USDC", amount: "3247.82" },
9      provider: "uniswap-v3",
10      fee: "1.62",
11      feeUSD: "1.62",
12      estimatedTime: 15,
13      priceImpact: 0.0005,
14      metadata: { pool: "0x88e6A0c2dDD26FEEb64F039a2c41296FcB3f5640", feeTier: 500 }
15    },
16    {
17      type: "bridge",
18      from: { chain: "ethereum", token: "USDC", amount: "3247.82" },
19      to: { chain: "solana", token: "USDC", amount: "3244.32" },
20      provider: "debridge",
21      fee: "3.50",
22      feeUSD: "3.50",
23      estimatedTime: 90,
24      priceImpact: 0,
25      metadata: { orderId: "0xabc123...", orderType: "DLN_FILL" }
26    },
27    {
28      type: "swap",
29      from: { chain: "solana", token: "USDC", amount: "3244.32" },
30      to: { chain: "solana", token: "SOL", amount: "14.32" },
31      provider: "jupiter",
32      fee: "0.97",
33      feeUSD: "0.97",
34      estimatedTime: 5,
35      priceImpact: 0.0008,
36      metadata: { routes: ["USDC→SOL"], slippageBps: 50 }
37    }
38  ],
39  expectedOutput: "14.32",
40  guaranteedMinimum: "13.85",
41  totalFees: "6.09",
42  totalFeesUSD: "6.09",
43  estimatedTime: 110,
44  minimaxScore: 0.847,
45  strategy: "minimax",
46  quotedAt: 1711152000000,
47  expiresAt: 1711152030000,
48  warnings: [],
49  penalties: {
50    slippage: "0.094",
51    gasSurge: "0.033",
52    mev: "0.043",
53    priceMovement: "0.072",
54    bridgeRisk: "0.007"
55  }
56}

1// router.execute() response
2{
3  execId: "exec_a7f3b2c1",
4  status: "completed",
5  actualOutput: "14.12",
6  totalTime: 134,
7  steps: [
8    {
9      index: 0,
10      total: 3,
11      hop: { /* ... swap hop ... */ },
12      status: "completed",
13      txHash: "0x1a2b3c4d5e6f...",
14      output: "3247.82",
15      gasUsed: "1.85",
16      startedAt: 1711152001000,
17      completedAt: 1711152016000
18    },
19    {
20      index: 1,
21      total: 3,
22      hop: { /* ... bridge hop ... */ },
23      status: "completed",
24      txHash: "0x7a8b9c0d1e2f...",
25      output: "3244.32",
26      gasUsed: "2.10",
27      startedAt: 1711152017000,
28      completedAt: 1711152107000
29    },
30    {
31      index: 2,
32      total: 3,
33      hop: { /* ... swap hop ... */ },
34      status: "completed",
35      txHash: "5YfgHi3jKlMnOp...",
36      output: "14.12",
37      gasUsed: "0.02",
38      startedAt: 1711152108000,
39      completedAt: 1711152135000
40    }
41  ],
42  txHashes: ["0x1a2b3c...", "0x7a8b9c...", "5YfgHi..."],
43  totalGasUsed: "3.97",
44  deviationFromQuote: -1.40,
45  meetsGuarantee: true,
46  fundsLocation: {
47    chain: "solana",
48    token: "SOL",
49    amount: "14.12",
50    status: "wallet"
51  }
52}

1import type {
2  // Router
3  MnmxRouter,
4  RouterConfig,
5  Strategy,
6  ScoringWeights,
7  AdversarialConfig,
8
9  // Route types
10  Route,
11  RouteHop,
12  RouteParams,
13  RouteOptions,
14  RouteWarning,
15  Quote,
16
17  // Execution types
18  ExecOpts,
19  ExecResult,
20  ExecStep,
21  ExecStatus,
22  FundsLocation,
23
24  // Bridge types
25  BridgeAdapter,
26  BridgeQuote,
27  BridgeResult,
28  BridgeStatus,
29  BridgeHealth,
30  BridgeMetrics,
31  LiquidityInfo,
32
33  // Chain types
34  ChainInfo,
35  TokenInfo,
36  ChainConfig,
37  GasEstimate,
38
39  // Signer types
40  EvmSigner,
41  SolanaSigner,
42  MultiChainSigner,
43
44  // Error types
45  NoRouteFoundError,
46  InsufficientLiquidityError,
47  SlippageExceededError,
48  BridgeTimeoutError,
49  ExecutionFailedError,
50  QuoteExpiredError,
51  UnsupportedChainError,
52  UnsupportedTokenError,
53  AmountBelowMinimumError,
54  InsufficientBalanceError,
55  AllEndpointsFailedError,
56} from '@mnmx/core';