SDK Documentation

Installation

# npm
npm install @qubismic/quantumdex-sdk viem

# pnpm
pnpm add @qubismic/quantumdex-sdk viem

# yarn
yarn add @qubismic/quantumdex-sdk viem

Quick Start

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

const account = privateKeyToAccount('0x...');

const walletClient = createWalletClient({
  account,
  chain: thichain,
  transport: http('https://rpc.thichain.io'),
});

const publicClient = createPublicClient({
  chain: thichain,
  transport: http('https://rpc.thichain.io'),
});

const dex = new QuantumDEXClient({
  publicClient,
  walletClient,
  // Optional: override contract addresses for testnet
  // addresses: TESTNET_ADDRESSES,
});

// Check karma score
const karma = await dex.karma.getScore(account.address);
console.log('Karma Score:', karma.score);    // e.g. 420
console.log('Fee Tier:', karma.tier);        // 'PRACTITIONER'

// Get swap quote
const quote = await dex.swap.getQuote({
  tokenIn: '0x...USDC',
  tokenOut: '0x...THI',
  amountIn: 100_000_000n,   // 100 USDC (6 decimals)
});
console.log('Expected out:', quote.amountOut);
console.log('Price impact:', quote.priceImpact, '%');

QuantumDEXClient

Constructor

new QuantumDEXClient(config: QuantumDEXClientConfig)

interface QuantumDEXClientConfig {
  publicClient: PublicClient;
  walletClient?: WalletClient;
  addresses?: Partial<ContractAddresses>;  // Override for testnet
}

Properties

Swap Methods

// Get swap quote (read-only)
const quote = await dex.swap.getQuote(params: SwapQuoteParams)
// Returns: { amountOut, priceImpact, feeBps, karmaTier, route }

// Get best route
const route = await dex.swap.getRoute(params: SwapRouteParams)

// Execute swap (requires walletClient)
const tx = await dex.swap.execute(route: SwapRoute, opts?: SwapOptions)
// Returns: { hash: `0x${string}`, wait: () => Promise<Receipt> }

// Approve token (if needed)
const approveTx = await dex.swap.approve({
  tokenAddress,
  amount,           // or 'MAX' for unlimited approval
})

Pool Methods

// Get pool data
const pool = await dex.pool.getPool(tokenA: Address, tokenB: Address)
// Returns: { reserves, totalSupply, feeBps, address }

// Add liquidity
const tx = await dex.pool.addLiquidity({
  tokenA, tokenB,
  amountADesired, amountBDesired,
  amountAMin, amountBMin,
  deadline,
})

// Remove liquidity
const tx = await dex.pool.removeLiquidity({
  tokenA, tokenB,
  liquidity,          // LP token amount
  amountAMin, amountBMin,
  deadline,
})

// Get LP position
const pos = await dex.pool.getPosition(userAddress, tokenA, tokenB)

Karma Methods

// Get karma score for any address
const karma = await dex.karma.getScore(address: Address)
// Returns: { score: number, tier: 'VISITOR'|'PRACTITIONER'|'GUARDIAN', feeBps: number }

// Get karma history (last N events)
const history = await dex.karma.getHistory(address, limit: number)

// Estimate karma impact of a transaction
const impact = await dex.karma.estimateImpact({
  from: address,
  type: 'SWAP' | 'LIQUIDITY' | 'GOVERNANCE' | 'BRIDGE',
  params: ...,
})

Error Handling

import { QuantumDEXError, ErrorCode } from '@qubismic/quantumdex-sdk';

try {
  const tx = await dex.swap.execute(route);
} catch (err) {
  if (err instanceof QuantumDEXError) {
    switch (err.code) {
      case ErrorCode.INSUFFICIENT_LIQUIDITY:
        // Pool doesn't have enough tokens
        break;
      case ErrorCode.SLIPPAGE_EXCEEDED:
        // Price moved too much — retry or increase tolerance
        break;
      case ErrorCode.DHARMIC_GATE_REJECTED:
        // Transaction failed 5-Yama ethical validation
        break;
      case ErrorCode.KARMA_BELOW_THRESHOLD:
        // Karma score too low for this operation
        break;
    }
  }
}