@sodax/dapp-kit

​

Features

• Swap/Intent — useQuote, useSwap, useSwapAllowance, useSwapApprove, useCancelSwap, useCreateLimitOrder, useCancelLimitOrder, useStatus
• Bridge — useBridge, useBridgeAllowance, useBridgeApprove, useGetBridgeableAmount, useGetBridgeableTokens
• Money Market — useSupply, useWithdraw, useBorrow, useRepay, useMMAllowance, useMMApprove, plus reserves data hooks
• Staking — useStake, useUnstake, useInstantUnstake, useClaim, useCancelUnstake, approval hooks, info/config/ratio queries
• DEX — useDexDeposit, useDexWithdraw, useSupplyLiquidity, useDecreaseLiquidity, useClaimRewards, pool/position queries, param builders
• Migration — useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD, useMigrateBaln, useMigrationApprove, useMigrationAllowance
• Bitcoin (Bound Exchange) — useRadfiAuth, useRadfiSession, useTradingWallet, useTradingWalletBalance, useBitcoinBalance, useFundTradingWallet, useRadfiWithdraw, useExpiredUtxos, useRenewUtxos
• Partner — useFetchAssetsBalances, useGetAutoSwapPreferences, useIsTokenApproved, useApproveToken, useSetSwapPreference, useFeeClaimSwap
• Recovery — useHubAssetBalances, useWithdrawHubAsset
• Backend Queries — Intent tracking, swap-tx submission + status, orderbook, money market position queries
• Shared — useXBalances, useDeriveUserWalletAddress, useGetUserHubWalletAddress, useStellarTrustlineCheck, useEstablishTrustline, useStellarGate, useEstimateGas
• Sponsoring — useStellarAccountActive, useStellarAccountStatus, useSponsorConfig, useActivateStellarAccount

​

Installation

pnpm add @sodax/dapp-kit @tanstack/react-query
# Optional: wallet connectivity
pnpm add @sodax/wallet-sdk-react

​

Quick Start

​

1. Set up providers

// providers.tsx
import { QueryClientProvider } from '@tanstack/react-query';
import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
import { ChainKeys, type SodaxOptions } from '@sodax/sdk';

const queryClient = createSodaxQueryClient();

const sodaxConfig: SodaxOptions = {
  chains: {
    [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
    [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
    [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://base.drpc.org' },
    [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
    // Add chains your dApp needs
  },
};

const walletConfig: SodaxWalletConfig = {
  EVM: {
    chains: {
      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
      [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://base.drpc.org' },
    },
  },
};

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <SodaxProvider config={sodaxConfig}>
      <QueryClientProvider client={queryClient}>
        <SodaxWalletProvider config={walletConfig}>
          {children}
        </SodaxWalletProvider>
      </QueryClientProvider>
    </SodaxProvider>
  );
}

​

2. Get a wallet provider

import { useWalletProvider } from '@sodax/wallet-sdk-react';
import { ChainKeys } from '@sodax/sdk';

function MyFeature() {
  const walletProvider = useWalletProvider(ChainKeys.BSC_MAINNET);
  // undefined until wallet is connected
}

​

3. Use feature hooks

import { useSwap } from '@sodax/dapp-kit';
import { useWalletProvider } from '@sodax/wallet-sdk-react';
import { ChainKeys } from '@sodax/sdk';
import type { CreateIntentParams } from '@sodax/sdk';

function SwapButton({ intentParams }: { intentParams: CreateIntentParams }) {
  const walletProvider = useWalletProvider(ChainKeys.BSC_MAINNET);
  const { mutateAsyncSafe: swap, isPending } = useSwap();

  const handleSwap = async () => {
    if (!walletProvider) return;
    const result = await swap({ params: intentParams, walletProvider });
    if (!result.ok) {
      alert(result.error instanceof Error ? result.error.message : 'Swap failed');
      return;
    }
    console.log('Swap submitted!', result.value);
  };

  return (
    <button onClick={handleSwap} disabled={isPending || !walletProvider}>
      {isPending ? 'Swapping...' : 'Swap'}
    </button>
  );
}

​

Requirements

• Node.js >= 20.12.0
• React >= 18
• TypeScript

​

API Reference

​

Provider

• SodaxProvider — Wraps your app, creates the Sodax SDK instance. Accepts config?: SodaxOptions.
• createSodaxQueryClient() — Factory for a QueryClient with global mutation observability (onMutationError hook, meta.silent opt-out).

​

Swap Hooks

• useQuote() — Real-time quote (auto-refreshes every 3s)
• useSwap() — Submit a cross-chain swap intent
• useSwapAllowance() — Check token approval
• useSwapApprove() — Approve token spending
• useStatus() — Track intent execution status
• useCancelSwap() — Cancel a pending swap
• useCreateLimitOrder() — Create a limit order (no deadline)
• useCancelLimitOrder() — Cancel a limit order

​

Money Market Hooks

• useSupply() — Supply collateral
• useWithdraw() — Withdraw supplied tokens
• useBorrow() — Borrow against collateral
• useRepay() — Repay borrowed tokens
• useMMAllowance() — Check approval (auto-skips for borrow/withdraw)
• useMMApprove() — Approve token spending
• useReservesData() — All reserve data
• useReservesHumanized() — Reserves in decimal-normalized format
• useReservesList() — List of reserve asset addresses
• useReservesUsdFormat() — Reserves with USD values
• useUserFormattedSummary() — User portfolio summary (health factor, collateral, debt)
• useUserReservesData() — User reserve positions
• useAToken() — aToken metadata
• useATokensBalances() — aToken balances

​

Bridge Hooks

• useBridge() — Execute a cross-chain bridge transfer
• useBridgeAllowance() — Check token approval
• useBridgeApprove() — Approve token spending
• useGetBridgeableAmount() — Max bridgeable amount between two tokens
• useGetBridgeableTokens() — Tokens bridgeable to a destination chain

​

Staking Hooks

• useStake() — Stake SODA, receive xSODA
• useUnstake() — Request unstake (waiting period)
• useInstantUnstake() — Instant unstake with slippage
• useClaim() — Claim SODA after waiting period
• useCancelUnstake() — Cancel pending unstake
• useStakeApprove() — Approve SODA for staking
• useUnstakeApprove() — Approve xSODA for unstaking
• useInstantUnstakeApprove() — Approve xSODA for instant unstaking
• useStakeAllowance() — Check SODA approval
• useUnstakeAllowance() — Check xSODA approval for unstaking
• useInstantUnstakeAllowance() — Check xSODA approval for instant unstaking
• useStakingInfo() — User staking position
• useUnstakingInfo() — Pending unstake requests
• useUnstakingInfoWithPenalty() — Unstake requests with penalty calcs
• useStakingConfig() — Unstaking period, max penalty
• useStakeRatio() — SODA-to-xSODA exchange rate
• useInstantUnstakeRatio() — Instant unstake rate
• useConvertedAssets() — xSODA to SODA conversion

​

DEX Hooks

• usePools() — List available pools
• usePoolData() — Pool details (price, tick, liquidity)
• usePoolBalances() — User pool token balances
• usePositionInfo() — Position details by token ID
• useDexDeposit() — Deposit assets into pool tokens
• useDexWithdraw() — Withdraw assets from pool tokens
• useDexAllowance() — Check approval for deposit
• useDexApprove() — Approve token spending
• useLiquidityAmounts() — Token amounts for a tick range
• useSupplyLiquidity() — Supply liquidity to a position
• useDecreaseLiquidity() — Remove liquidity
• useClaimRewards() — Claim trading fees
• useCreateDepositParams() — Build deposit params with ERC-4626 conversion
• useCreateWithdrawParams() — Build withdraw params
• useCreateSupplyLiquidityParams() — Build tick range + liquidity params
• useCreateDecreaseLiquidityParams() — Build decrease params from position state

​

Migration Hooks

• useMigrateIcxToSoda() — ICX/wICX (ICON) → SODA (Sonic)
• useRevertMigrateSodaToIcx() — SODA (Sonic) → wICX (ICON)
• useMigratebnUSD() — Legacy bnUSD ↔ new bnUSD (bidirectional)
• useMigrateBaln() — BALN (ICON) → SODA with optional lock period
• useMigrationApprove() — Approve token spending before migration
• useMigrationAllowance() — Check if approval is needed

​

Bitcoin (Bound Exchange) Hooks

• useRadfiSession() — Manage Bound Exchange session (login, auto-refresh)
• useRadfiAuth() — Authenticate with Bound Exchange via BIP322 signing
• useTradingWallet() — Get trading wallet address from persisted session
• useBitcoinBalance() — BTC balance for any address
• useTradingWalletBalance() — Trading wallet balance from Bound Exchange API
• useFundTradingWallet() — Fund trading wallet from personal wallet
• useRadfiWithdraw() — Withdraw from trading wallet
• useExpiredUtxos() — Fetch expired UTXOs (polls every 60s)
• useRenewUtxos() — Renew expired UTXOs

​

Partner Hooks

• useFetchAssetsBalances() — Fetch partner asset balances
• useGetAutoSwapPreferences() — Get auto-swap preferences
• useIsTokenApproved() — Check token approval
• useApproveToken() — Approve token
• useSetSwapPreference() — Set swap preference
• useFeeClaimSwap() — Claim partner fees via swap

​

Recovery Hooks

• useHubAssetBalances() — Get hub asset balances
• useWithdrawHubAsset() — Withdraw hub asset

​

Shared Hooks

• useSodaxContext() — Access the Sodax SDK instance
• useHubProvider() — Access the hub chain (Sonic) provider
• useXBalances() — Cross-chain token balances for an address
• useDeriveUserWalletAddress() — Derive hub wallet address (CREATE3)
• useGetUserHubWalletAddress() — Derive hub wallet address (wallet router)
• useEstimateGas() — Estimate gas for transactions
• useStellarTrustlineCheck() — Check Stellar trustline
• useEstablishTrustline() — Request Stellar trustline
• useRequestTrustline() — Deprecated, use useEstablishTrustline()
• useStellarGate() — Sequences the Stellar destination prerequisites (activation → funding → trustline)

​

Sponsoring Hooks

• useStellarAccountActive() — Whether a Stellar account exists on-chain
• useStellarAccountStatus() — Existence plus whether the account can afford a trustline
• useSponsorConfig() — Sponsor account, network, fee band, max time bounds
• useActivateStellarAccount() — Activate a Stellar account via the sponsor

​

Backend Query Hooks

• useBackendIntentByTxHash() — Get intent by hub tx hash (polls 1s)
• useBackendIntentByHash() — Get intent by intent hash
• useBackendUserIntents() — All intents for a user with date filtering
• useBackendOrderbook() — Solver orderbook (cached 30s, no auto-refetch)
• useBackendMoneyMarketPosition() — User money market position
• useBackendAllMoneyMarketAssets() — All MM assets
• useBackendMoneyMarketAsset() — Single MM asset details
• useBackendMoneyMarketAssetBorrowers() — Asset borrowers
• useBackendMoneyMarketAssetSuppliers() — Asset suppliers
• useBackendAllMoneyMarketBorrowers() — All borrowers
• useBackendOracleMarkets() — Oracle candle discovery: quote, intervals, symbols (cached 60s)
• useBackendOracleCandles() — USD OHLC candles for a symbol over [from, to) (cached 10s)

​

Swaps API Hooks (sodax.api.swaps)

• useSwapsApiQuote() — Solver quote for a cross-chain swap
• useSwapsApiCreateIntent() — Build an unsigned create-intent tx
• useSwapsApiSubmitTx() — Submit swap tx to backend
• useSwapsApiSubmitTxStatus() — Check submitted swap status

​

DEX Utils

• createDepositParamsProps() — Build deposit params from pool data and spoke asset info
• createWithdrawParamsProps() — Build withdraw params with optional destination info
• createSupplyLiquidityParamsProps() — Build concentrated liquidity supply params
• createDecreaseLiquidityParamsProps() — Build decrease liquidity params

​

Development

pnpm install     # Install dependencies
pnpm build       # Build the package (ESM + CJS)
pnpm dev         # Watch mode
pnpm checkTs     # Type checking
pnpm test        # Run tests
pnpm pretty      # Format code
pnpm lint        # Lint code

​

AI agent docs

npx skills@latest add icon-project/sodax-sdks/packages/skills

pnpm add -D @sodax/skills

​

License

​

Support

• GitHub Issues
• Discord Community