@sodax/dapp-kit

​

Features

• Swap/Intent — useQuote, useSwap, useSwapAllowance, useSwapApprove, useCancelSwap, useCreateLimitOrder, useCancelLimitOrder, useStatus
• Bridge — useBridge, useBridgeDetailedStatus, 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
• Leverage Yield — useLeverageYieldDeposit, useLeverageYieldWithdraw, useLeverageYieldVaultSwap, useLeverageYieldDetailedStatus, useLeverageYieldNotifySolver, plus vault position/APR/TVL/share queries
• Migration — useMigrateIcxToSoda, useRevertMigrateSodaToIcx, useMigratebnUSD, useMigrateBaln, useMigrationApprove, useMigrationAllowance
• Bitcoin (Bound Exchange) — useRadfiAuth, useEnsureRadfiAccessToken, useRadfiSession, useTradingWallet, useTradingWalletBalance, useBitcoinBalance, useBitcoinTradingSetup, useFundTradingWallet, useRadfiWithdraw, useExpiredUtxos, useRenewUtxos
• Partner — useFetchAssetsBalances, useGetAutoSwapPreferences, useIsTokenApproved, useApproveToken, useSetSwapPreference, useFeeClaimSwap, useFeeClaimWithdraw, usePartnerCancelIntent, useGetUserIntent, useGetIntentDetails
• Recovery — useHubAssetBalances, useWithdrawHubAsset
• Backend Queries — Intent tracking, swap-tx submission + status, orderbook, money market position queries
• Shared — useXBalances, useDeriveUserWalletAddress, useGetUserHubWalletAddress, useStellarTrustlineCheck, useEstablishTrustline, useStellarGate, useNearStorageCheck, useRegisterNearStorage, useNearStorageGate, 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 >= 22.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
• useBridgeDetailedStatus() — Track a bridge from its source tx, whichever completion path ran
• 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

​

Leverage Position Hooks

• useOpenLeveragePosition() — Open a position (side: 'collateral' | 'debt') and report its intent
• useSubmitLeveragePositionIntent() — Run increaseLeverage / decreaseLeverage and report the intent
• useRunLeveragePositionOperation() — Run withdraw / settle / cancel; no intent, nothing to report
• useLeveragePositionPayoutAddress() — Where a withdrawal can be paid, which off the hub is not the signer
• useLeveragePositionFundingAllowance() — Whether the funding token is approved; the spender is chain-dependent
• useApproveLeveragePositionFunding() — Approve it, against the spender the SDK resolves
• useLeveragePositionsForUser() — A user’s positions, discovered through their hub wallet
• useLeveragePositionAccount() — Collateral, debt, LTV and health factor
• useLeveragePositionInfo() — The position’s collateral and borrow reserves
• useLeveragePositionCollateral() — Collateral balance held
• useLeveragePositionPending() — The pending-operation slot; a position permits one at a time

Resolving means the intent is live, not that leverage moved. Off-hub (spoke) origins are experimental and unverified on-chain; see each hook’s JSDoc.

​

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

​

Leverage Yield Hooks

• useLeverageYieldEffectiveApr() — Vault effective APR (AAVE rates + LSD yield, leverage-adjusted; refreshes 60s)
• useLeverageYieldPosition() — Live position snapshot: collateral, debt, LTV, health factor, idle assets (refreshes 30s)
• useLeverageYieldTotalAssets() — Vault total underlying assets (TVL)
• useLeverageYieldPreviewRedeem() — Assets received for redeeming shares (ERC-4626 previewRedeem)
• useLeverageYieldShareBalances() — User lsoda* share balances across every chain they may hold a position under
• useLeverageYieldDeposit() — Build the deposit payload (any token → lsoda* shares) for useLeverageYieldVaultSwap
• useLeverageYieldWithdraw() — Build the withdraw payload (lsoda* shares → any token) for useLeverageYieldVaultSwap
• useLeverageYieldVaultSwap() — Execute an end-to-end vault swap (deposit or withdraw); backend 2-step by default, with the client-side fallback
• useLeverageYieldDetailedStatus() — Track a vault swap from its source tx, whichever completion path ran
• useLeverageYieldNotifySolver() — Notify the solver that a vault intent landed on the hub (standalone step for manual relay flows)

​

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
• useEnsureRadfiAccessToken() — Ensure a valid Bound Exchange access token (refresh, or full re-auth), returning it for a Bitcoin-source createIntent
• useTradingWallet() — Get trading wallet address from persisted session
• useBitcoinBalance() — BTC balance for any address
• useTradingWalletBalance() — Trading wallet balance from Bound Exchange API
• useBitcoinTradingSetup() — Bitcoin trading-wallet setup for one side of a cross-chain flow (inert unless the chain is Bitcoin)
• 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
• useFeeClaimWithdraw() — Withdraw a partner fee balance via a Sonic-sourced bridge to the destination chain
• usePartnerCancelIntent() — Cancel a stuck partner fee-claim auto-swap intent and recover the locked tokens
• useGetUserIntent() — Look up the stored intent hash for a partner (user, fromToken, toToken) pair
• useGetIntentDetails() — Fetch the full intent details for a ProtocolIntents intent hash

​

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)
• useNearStorageCheck() — Check NEP-141 storage registration for a token on NEAR (NEAR’s analogue of a Stellar trustline)
• useRegisterNearStorage() — Submit a NEP-141 storage_deposit so a NEAR account can receive a token
• useNearStorageGate() — Derive the NEP-141 storage-registration UI gate state for a NEAR delivery

​

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

​

Bridge API Hooks (sodax.api.bridge)

• useBridgeApiSubmitTx() — Hand a broadcast spoke-deposit tx to the backend relay pipeline
• useBridgeApiSubmitTxStatus() — Poll a submitted bridge tx by (txHash, srcChainKey)

​

API-key failures are terminal

​

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

• resolveNearStorageGate() — Derive the NEP-141 storage-registration UI gate state (hook-free counterpart of useNearStorageGate)

​

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