@sodax/dapp-kit

High-level React hooks library for dApp developers. Wraps @sodax/sdk with React Query into feature-organized hooks. Used alongside @sodax/wallet-sdk-react (no direct dependency — shared types come from @sodax/sdk).

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, orderbook, money market position queries

• Shared — useXBalances, useDeriveUserWalletAddress, useGetUserHubWalletAddress, useStellarTrustlineCheck, useRequestTrustline, useEstimateGas

Installation

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

Quick Start

1. Set up providers

RPC URLs are injected through config.chains. SodaxProvider is the outermost wrapper; QueryClientProvider wraps everything inside it.

// 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 DeepPartial, type SodaxConfig } from '@sodax/sdk';

const queryClient = createSodaxQueryClient();

const sodaxConfig: DeepPartial<SodaxConfig> = {
  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

All mutation hooks accept no arguments at initialization. Domain inputs (params, walletProvider) flow through mutate(vars):

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?: DeepPartial<SodaxConfig>.

• 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

• useRequestTrustline() — Request Stellar trustline

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

• useBackendSubmitSwapTx() — Submit swap tx to backend

• useBackendSubmitSwapTxStatus() — 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

AI-readable docs for @sodax/dapp-kit (and the other @sodax/* packages) are shipped via @sodax/skills — a separate npm package bundling Claude-Code SKILL.md files and a long-form knowledge tree.

Recommended: skills CLI — from your project root:

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

npm + AGENTS.md pointer (fallback for web chats, or when you prefer a devDependency over the CLI):

pnpm add -D @sodax/skills

Then point your agent at node_modules/@sodax/skills/AGENTS.md. See docs/ai-integration-guide.md for all install modes and per-tool wiring.

License

MIT

Support

• GitHub Issues

• Discord Community