Swap — QuantumDEX

How Swaps Work

QuantumDEX swaps use the constant product AMM formula (x · y = k) implemented in QuantumPair.sol. Every token pair has its own liquidity pool. The QuantumRouter routes your swap through the optimal path and handles all token approvals.

Swap Flow

You approve the QuantumRouter to spend your input token
Router calls swapExactTokensForTokens() or swapTokensForExactTokens()
The KarmaOracle precompile (0x0421) is consulted to determine your fee tier
Fee is deducted, remaining tokens swap through the x·y=k invariant
Output tokens arrive in your wallet in the same ThiChain transaction (~2 second block time)

Karma Fee Tiers

Your fee is determined by your wallet's on-chain Karma Score, computed by the ThiChain Dharmic Validator:

Tier	Karma Score	Fee	Notes
Visitor	0–250	30 BPS (0.30%)	Default for new wallets
Practitioner	251–750	15 BPS (0.15%)	Achieved through constructive on-chain behaviour
Guardian	751+	0–15 BPS (scaled)	High-karma wallets approaching zero-fee trading

Karma Score is earned, not bought. It reflects your history of honest, non-harmful transactions on ThiChain. It is separate from QBIT token holdings.

Price Impact

Price impact increases with trade size relative to pool liquidity. QuantumDEX shows estimated price impact before you confirm. As a guideline:

< 0.5% — Excellent liquidity. Proceed normally.
0.5% – 2% — Moderate impact. Consider splitting the trade.
> 2% — High impact. QuantumDEX will warn you before confirmation.

Slippage Tolerance

The minimum amount you are willing to receive is set via the amountOutMin parameter in swapExactTokensForTokens(). The default UI slippage tolerance is 0.5%. You can adjust this in Settings before swapping.

// Example: Swap 100 USDC for at least 99.5 THI (0.5% slippage)
await router.swapExactTokensForTokens(
  parseUnits("100", 6),   // amountIn (USDC)
  parseUnits("99.5", 18), // amountOutMin (THI)
  [USDC_ADDRESS, THI_ADDRESS],
  userAddress,
  deadline
);

SDK Example

import { QuantumDEXClient } from '@qubismic/quantumdex-sdk';
import { createWalletClient, http } from 'viem';
import { thichain } from '@qubismic/quantumdex-sdk/chains';

const client = new QuantumDEXClient({
  chain: thichain,          // Chain ID 420420
  transport: http('https://rpc.thichain.io'),
  walletClient: myWalletClient,
});

// Get best swap route
const route = await client.getSwapRoute({
  tokenIn:  '0x...USDC',
  tokenOut: '0x...THI',
  amountIn: parseUnits('100', 6),
});

console.log('Karma fee tier:', route.karmaTier);     // 'PRACTITIONER'
console.log('Fee BPS:', route.feeBps);               // 15
console.log('Expected output:', route.amountOut);

// Execute swap
const tx = await client.executeSwap(route, {
  slippageTolerance: 0.005,   // 0.5%
});

console.log('TX hash:', tx.hash);

See the full SDK Documentation for all available methods.

Swap Tokens