@sodax/dapp-kit 2.0.0-rc.2 → 2.0.0-rc.4

package/ai-exported/integration/recipes/setup.md

@@ -1,144 +0,0 @@
-# Recipe: Setup
-
-Install and wire `@sodax/dapp-kit` into a React project.
-
-**Depends on:** None
-
-## Install
-
-```bash
-# Required
-pnpm add @sodax/dapp-kit @tanstack/react-query
-
-# Optional (only if you want built-in wallet connectivity hooks + providers)
-pnpm add @sodax/wallet-sdk-react
-```
-
-## Wire Providers
-
-RPC URLs are injected via `config.chains` — each chain entry takes `{ rpcUrl: string }`.
-
-```tsx
-// providers.tsx
-import { QueryClientProvider } from '@tanstack/react-query';
-import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
-import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
-
-const queryClient = createSodaxQueryClient();
-
-const sodaxConfig: DeepPartial<SodaxConfig> = {
-  chains: {
-    [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: 'https://arb1.arbitrum.io/rpc' },
-    [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
-    [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
-    [ChainKeys.POLYGON_MAINNET]: { rpcUrl: 'https://polygon-rpc.com' },
-    // Add chains your dApp needs
-  },
-};
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <SodaxProvider config={sodaxConfig}>
-      <QueryClientProvider client={queryClient}>
-        {children}
-      </QueryClientProvider>
-    </SodaxProvider>
-  );
-}
-```
-
-### Optional: Add Wallet Provider
-
-If you want to use `@sodax/wallet-sdk-react` for wallet connectivity, wrap `SodaxWalletProvider` inside `QueryClientProvider`:
-
-```tsx
-// @ai-snippets-skip
-import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
-
-const walletConfig: SodaxWalletConfig = {
-  EVM: {
-    chains: {
-      [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
-      [ChainKeys.BASE_MAINNET]: { rpcUrl: 'https://mainnet.base.org' },
-    },
-  },
-};
-
-export function Providers({ children }: { children: React.ReactNode }) {
-  return (
-    <SodaxProvider config={sodaxConfig}>
-      <QueryClientProvider client={queryClient}>
-        <SodaxWalletProvider config={walletConfig}>{children}</SodaxWalletProvider>
-      </QueryClientProvider>
-    </SodaxProvider>
-  );
-}
-```
-
-## `createSodaxQueryClient` (optional)
-
-`createSodaxQueryClient` returns a `QueryClient` pre-wired with a `MutationCache.onError` hook for global mutation observability. Use it instead of `new QueryClient()`:
-
-```tsx
-// @ai-snippets-skip — illustrative — multiple createSodaxQueryClient variations
-import { createSodaxQueryClient } from '@sodax/dapp-kit';
-
-// Default: logs every mutation failure as `[sodax] Mutation error: <error>`
-const queryClient = createSodaxQueryClient();
-
-// Wire to your own logger
-const queryClient = createSodaxQueryClient({
-  onMutationError: (e) => Sentry.captureException(e),
-});
-
-// Silence a specific mutation locally via meta.silent
-const swap = useSwap({
-  mutationOptions: { meta: { silent: true }, onError: (e) => toast.error(e.message) },
-});
-```
-
-## Initialize SDK (Optional)
-
-For dynamic config (latest tokens/chains from backend API):
-
-```tsx
-import { useEffect } from 'react';
-import { useSodaxContext } from '@sodax/dapp-kit';
-
-export function useInitializeSodax() {
-  const { sodax } = useSodaxContext();
-
-  useEffect(() => {
-    sodax.initialize().then((result) => {
-      if (!result.ok) console.error('Failed to initialize Sodax:', result.error);
-    });
-  }, [sodax]);
-}
-```
-
-## Chain Key Constants
-
-```tsx
-import { ChainKeys } from '@sodax/sdk';
-
-// Examples (full list lives in @sodax/sdk's reference):
-ChainKeys.SONIC_MAINNET;       // 'sonic'           (hub)
-ChainKeys.ARBITRUM_MAINNET;    // '0xa4b1.arbitrum'
-ChainKeys.BASE_MAINNET;        // '0x2105.base'
-ChainKeys.BSC_MAINNET;         // '0x38.bsc'
-ChainKeys.ETHEREUM_MAINNET;    // '0x1.ethereum'
-ChainKeys.POLYGON_MAINNET;     // '0x89.polygon'
-ChainKeys.OPTIMISM_MAINNET;    // '0xa.optimism'
-ChainKeys.AVALANCHE_MAINNET;   // '0xa86a.avax'
-ChainKeys.SUI_MAINNET;         // 'sui'
-ChainKeys.STELLAR_MAINNET;     // 'stellar'
-ChainKeys.SOLANA_MAINNET;      // 'solana'
-ChainKeys.ICON_MAINNET;        // '0x1.icon'
-ChainKeys.INJECTIVE_MAINNET;   // 'injective-1'
-ChainKeys.NEAR_MAINNET;        // 'near'
-ChainKeys.STACKS_MAINNET;      // 'stacks'
-ChainKeys.BITCOIN_MAINNET;     // 'bitcoin'
-// HyperEVM, Lightlink, Redbelly, Kaia also available.
-```
-
-**v1 → v2:** the legacy `*_MAINNET_CHAIN_ID` constants (e.g. `BSC_MAINNET_CHAIN_ID`) are gone. Use `ChainKeys.X_MAINNET` namespace access.

package/ai-exported/integration/recipes/staking.md

@@ -1,202 +0,0 @@
-# Recipe: Staking
-
-SODA token staking via xSODA ERC-4626 vault.
-
-**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
-
-## Hooks
-
-### Mutations
-
-| Hook | Purpose |
-|------|---------|
-| `useStake` | Stake SODA, receive xSODA |
-| `useStakeApprove` | Approve SODA for staking |
-| `useUnstake` | Request unstake (waiting period) |
-| `useUnstakeApprove` | Approve xSODA for unstaking |
-| `useInstantUnstake` | Instant unstake with slippage |
-| `useInstantUnstakeApprove` | Approve xSODA for instant unstaking |
-| `useClaim` | Claim SODA after waiting period |
-| `useCancelUnstake` | Cancel pending unstake |
-
-### Queries
-
-| Hook | Purpose |
-|------|---------|
-| `useStakeAllowance` | Check SODA approval for staking |
-| `useUnstakeAllowance` | Check xSODA approval for unstaking |
-| `useInstantUnstakeAllowance` | Check xSODA approval for instant unstaking |
-| `useStakingInfo` | Staking position (total staked, xSODA balance, value) |
-| `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 |
-
-## Staking Dashboard
-
-```tsx
-import { useStakingInfo, useStakingConfig, useStakeRatio } from '@sodax/dapp-kit';
-import type { SpokeChainKey } from '@sodax/sdk';
-import { formatUnits } from 'viem';
-
-function StakingDashboard({ srcAddress, srcChainKey }: { srcAddress: `0x${string}`; srcChainKey: SpokeChainKey }) {
-  const { data: info } = useStakingInfo({ params: { srcAddress, srcChainKey } });
-  const { data: config } = useStakingConfig({});
-  const { data: ratio } = useStakeRatio({ params: { amount: 1000000000000000000n } });
-
-  if (!info) return <div>Loading...</div>;
-  return (
-    <div>
-      <p>Total Staked: {formatUnits(info.totalStaked, 18)} SODA</p>
-      <p>Your xSODA: {formatUnits(info.userXSodaBalance, 18)}</p>
-      <p>Your Value: {formatUnits(info.userXSodaValue, 18)} SODA</p>
-      {ratio && <p>Rate: 1 SODA = {formatUnits(ratio[0], 18)} xSODA</p>}
-      {config && <p>Unstaking: {(Number(config.unstakingPeriod) / 86400).toFixed(1)} days</p>}
-    </div>
-  );
-}
-```
-
-## Stake
-
-```tsx
-import { useState } from 'react';
-import { useStake, useStakeAllowance, useStakeApprove, useStakeRatio } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import { parseUnits, formatUnits, type Address } from 'viem';
-
-function StakeForm({ srcAddress }: { srcAddress: Address }) {
-  const [amount, setAmount] = useState('');
-  const chainKey = ChainKeys.BASE_MAINNET;
-  const walletProvider = useWalletProvider({ xChainId: chainKey });
-  const parsedAmount = amount ? parseUnits(amount, 18) : 0n;
-
-  const { data: ratio } = useStakeRatio({ params: { amount: parsedAmount } });
-
-  const stakeParams = parsedAmount > 0n
-    ? { srcChainKey: chainKey, srcAddress, amount: parsedAmount, minReceive: ratio ? (ratio[0] * 95n) / 100n : 0n, action: 'stake' as const }
-    : undefined;
-
-  // useStakeAllowance wraps `Omit<StakeParams, 'action'>` under params.payload. Read-only,
-  // no walletProvider needed (calls `staking.isAllowanceValid` with `raw: true` internally).
-  const { data: isApproved } = useStakeAllowance({
-    params: stakeParams
-      ? { payload: { srcChainKey: chainKey, srcAddress, amount: parsedAmount, minReceive: stakeParams.minReceive } }
-      : undefined,
-  });
-  const { mutateAsync: approve, isPending: isApproving } = useStakeApprove();
-  const { mutateAsync: stake, isPending: isStaking } = useStake();
-
-  const handleStake = async () => {
-    if (!stakeParams || !walletProvider) return;
-    try {
-      if (!isApproved) await approve({ params: stakeParams, walletProvider });
-      const txHashPair = await stake({ params: stakeParams, walletProvider });
-      console.log('Staked:', txHashPair);
-    } catch (e) {
-      console.error(e);
-    }
-  };
-
-  return (
-    <div>
-      <input placeholder="SODA amount" value={amount} onChange={(e) => setAmount(e.target.value)} />
-      {ratio && <p>~{formatUnits(ratio[0], 18)} xSODA</p>}
-      <button onClick={handleStake} disabled={isStaking || isApproving || !stakeParams || !walletProvider}>
-        {isApproving ? 'Approving...' : isStaking ? 'Staking...' : 'Stake'}
-      </button>
-    </div>
-  );
-}
-```
-
-## Unstake + Claim
-
-```tsx
-import { useUnstakingInfoWithPenalty, useClaim } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import { formatUnits, type Address } from 'viem';
-
-function UnstakePanel({ srcAddress }: { srcAddress: Address }) {
-  const chainKey = ChainKeys.BASE_MAINNET;
-  const walletProvider = useWalletProvider({ xChainId: chainKey });
-  const { data: info } = useUnstakingInfoWithPenalty({ params: { srcAddress, srcChainKey: chainKey } });
-  const { mutateAsync: claim } = useClaim();
-
-  return (
-    <div>
-      {info?.requestsWithPenalty.map((req, i) => (
-        <div key={i}>
-          <p>{formatUnits(req.claimableAmount, 18)} SODA claimable (penalty: {req.penaltyPercentage}%)</p>
-          <button
-            onClick={() => walletProvider && claim({
-              // req.id is the requestId on the UserUnstakeInfo shape; req.request holds the
-              // original UnstakeSodaRequest. ClaimParams takes the id and the post-penalty amount.
-              params: { srcChainKey: chainKey, srcAddress, requestId: req.id, amount: req.claimableAmount, action: 'claim' },
-              walletProvider,
-            })}
-          >
-            Claim
-          </button>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Instant Unstake
-
-```tsx
-import { useInstantUnstake, useInstantUnstakeRatio } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import { type Address } from 'viem';
-
-function InstantUnstakeButton({ xSodaAmount, srcAddress }: { xSodaAmount: bigint; srcAddress: Address }) {
-  const chainKey = ChainKeys.BASE_MAINNET;
-  const walletProvider = useWalletProvider({ xChainId: chainKey });
-  const { data: ratio } = useInstantUnstakeRatio({ params: { amount: xSodaAmount } });
-  const { mutateAsync: instantUnstake, isPending } = useInstantUnstake();
-
-  return (
-    <button
-      disabled={isPending || !walletProvider}
-      onClick={() => walletProvider && instantUnstake({
-        params: {
-          srcChainKey: chainKey,
-          srcAddress,
-          amount: xSodaAmount,
-          minAmount: ratio ? (ratio * 95n) / 100n : 0n,
-          action: 'instantUnstake',
-        },
-        walletProvider,
-      })}
-    >
-      {isPending ? 'Processing...' : 'Instant Unstake'}
-    </button>
-  );
-}
-```
-
-## Types
-
-```typescript
-type StakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; minReceive: bigint; action: 'stake' };
-type UnstakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; action: 'unstake' };
-type InstantUnstakeParams<K> = { srcChainKey: K; srcAddress: Address; amount: bigint; minAmount: bigint; action: 'instantUnstake' };
-type ClaimParams<K> = { srcChainKey: K; srcAddress: Address; requestId: bigint; amount: bigint; action: 'claim' };
-type CancelUnstakeParams<K> = { srcChainKey: K; srcAddress: Address; requestId: bigint; action: 'cancelUnstake' };
-// All wrapped as: { params: ParamsType, walletProvider }
-```
-
-## Notes
-
-- **Unstaking period**: configurable, check `useStakingConfig`.
-- **Penalty**: linear from `maxPenalty` to 0 over the unstaking period.
-- **Instant unstake**: no waiting, but pays slippage via StakingRouter.
-- Query hooks (`useStakingInfo`, `useUnstakingInfoWithPenalty`, etc.) take `{ params: { srcAddress, srcChainKey } }` — they derive the hub wallet internally.

package/ai-exported/integration/recipes/swap.md

@@ -1,272 +0,0 @@
-# Recipe: Swap
-
-Cross-chain token swaps via the intent-based solver.
-
-**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
-
-## Hooks
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useQuote` | Query | Real-time swap quote (auto-refreshes 3s) |
-| `useSwap` | Mutation | Execute a complete cross-chain swap |
-| `useSwapAllowance` | Query | Check if token approval is needed |
-| `useSwapApprove` | Mutation | Approve tokens for the swap contract |
-| `useStatus` | Query | Track intent execution status |
-| `useCancelSwap` | Mutation | Cancel an active swap intent |
-| `useCreateLimitOrder` | Mutation | Create a limit order (no deadline) |
-| `useCancelLimitOrder` | Mutation | Cancel an active limit order |
-
-## Get a Quote
-
-```tsx
-import { useQuote } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/sdk';
-
-function SwapQuote({ inputAmount }: { inputAmount: bigint }) {
-  const { data: quoteResult, isLoading } = useQuote({
-    params: {
-      payload: inputAmount > 0n
-        ? {
-            token_src: '0x2170Ed0880ac9A755fd29B2688956BD959F933F8',
-            token_dst: '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f',
-            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
-            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
-            amount: inputAmount,
-            quote_type: 'exact_input',
-          }
-        : undefined,
-    },
-  });
-
-  if (isLoading) return <div>Fetching quote...</div>;
-  if (quoteResult?.ok) return <div>Output: {quoteResult.value.quoted_amount}</div>;
-  return null;
-}
-```
-
-## Check Allowance + Approve
-
-```tsx
-import { useSwapAllowance, useSwapApprove } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import type { CreateIntentParams } from '@sodax/sdk';
-
-function SwapApproval({ intentParams }: { intentParams: CreateIntentParams }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-
-  // useSwapAllowance wraps the request under params.payload and takes walletProvider + srcChainKey
-  // alongside (all under `params`, not at the top level).
-  const { data: isApproved } = useSwapAllowance({
-    params: {
-      payload: intentParams,
-      srcChainKey: ChainKeys.BSC_MAINNET,
-      walletProvider,
-    },
-  });
-  const { mutateAsync: approve, isPending } = useSwapApprove();
-
-  // useSwapAllowance data is `boolean | undefined` (already unwrapped from Result by the hook).
-  if (isApproved) return null;
-  return (
-    <button onClick={() => walletProvider && approve({ params: intentParams, walletProvider })} disabled={isPending}>
-      {isPending ? 'Approving...' : 'Approve Token'}
-    </button>
-  );
-}
-```
-
-## Execute Swap
-
-```tsx
-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({ xChainId: ChainKeys.BSC_MAINNET });
-  const { mutateAsync: swap, isPending } = useSwap();
-
-  const handleSwap = async () => {
-    if (!walletProvider) return;
-    try {
-      const { solverExecutionResponse, intent, intentDeliveryInfo } = await swap({
-        params: intentParams,
-        walletProvider,
-      });
-      console.log('Swap successful!', solverExecutionResponse);
-    } catch (e) {
-      // surfaced via mutation.error / onError
-    }
-  };
-
-  return (
-    <button onClick={handleSwap} disabled={isPending || !walletProvider}>
-      {isPending ? 'Swapping...' : 'Swap'}
-    </button>
-  );
-}
-```
-
-## Full Example
-
-```tsx
-import { useState } from 'react';
-import { useQuote, useSwap, useSwapAllowance, useSwapApprove } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-import type { CreateIntentParams, SolverIntentQuoteRequest } from '@sodax/sdk';
-import { parseUnits } from 'viem';
-
-const SRC_TOKEN = '0x2170Ed0880ac9A755fd29B2688956BD959F933F8';
-const DST_TOKEN = '0x2f2a2543B76A4166549F7aaB2e75Bef0aefC5B0f';
-
-export function SwapPage() {
-  const [inputAmount, setInputAmount] = useState('');
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  const parsedAmount = inputAmount ? parseUnits(inputAmount, 18) : 0n;
-
-  // 1. Quote — useQuote takes { params: { payload: SolverIntentQuoteRequest } }.
-  const { data: quoteResult, isLoading: isQuoting } = useQuote({
-    params: {
-      payload: parsedAmount > 0n
-        ? {
-            token_src: SRC_TOKEN,
-            token_dst: DST_TOKEN,
-            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
-            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
-            amount: parsedAmount,
-            quote_type: 'exact_input',
-          }
-        : undefined,
-    },
-  });
-
-  // 2. Build intent params. The request-side fields are `srcChainKey` / `dstChainKey`
-  // (distinct from the read-side `Intent.srcChain` / `Intent.dstChain` which are
-  // `IntentRelayChainId` bigints — a separate shape).
-  const intentParams: CreateIntentParams | undefined =
-    quoteResult?.ok
-      ? {
-          inputToken: SRC_TOKEN,
-          outputToken: DST_TOKEN,
-          inputAmount: parsedAmount,
-          minOutputAmount: BigInt(quoteResult.value.quoted_amount),
-          deadline: 0n,
-          allowPartialFill: false,
-          srcChainKey: ChainKeys.BSC_MAINNET,
-          dstChainKey: ChainKeys.ARBITRUM_MAINNET,
-          srcAddress: '0x0000000000000000000000000000000000000000', // connected wallet address
-          dstAddress: '0x0000000000000000000000000000000000000000', // destination address
-          solver: '0x0000000000000000000000000000000000000000',
-          data: '0x',
-        }
-      : undefined;
-
-  // 3. Allowance — useSwapAllowance nests payload + srcChainKey + walletProvider under params.
-  const { data: isApproved } = useSwapAllowance({
-    params: intentParams
-      ? { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider }
-      : undefined,
-  });
-
-  // 4. Approve + Swap (using mutateAsyncSafe — no try/catch, no unhandled rejections)
-  const { mutateAsyncSafe: approve, isPending: isApproving } = useSwapApprove();
-  const { mutateAsyncSafe: swap, isPending: isSwapping } = useSwap();
-
-  const handleSwap = async () => {
-    if (!intentParams || !walletProvider) return;
-    if (!isApproved) {
-      const r = await approve({ params: intentParams, walletProvider });
-      if (!r.ok) { alert(r.error instanceof Error ? r.error.message : 'Approve failed'); return; }
-    }
-    const r = await swap({ params: intentParams, walletProvider });
-    if (r.ok) alert('Swap successful!');
-    else alert(r.error instanceof Error ? r.error.message : 'Swap failed');
-  };
-
-  return (
-    <div>
-      <input placeholder="Amount" value={inputAmount} onChange={(e) => setInputAmount(e.target.value)} />
-      {isQuoting && <p>Fetching quote...</p>}
-      {quoteResult?.ok && <p>Output: {quoteResult.value.quoted_amount}</p>}
-      <button onClick={handleSwap} disabled={isSwapping || isApproving || !intentParams}>
-        {isApproving ? 'Approving...' : isSwapping ? 'Swapping...' : 'Swap'}
-      </button>
-    </div>
-  );
-}
-```
-
-## Limit Orders
-
-```tsx
-import { useCreateLimitOrder, useCancelLimitOrder } from '@sodax/dapp-kit';
-import type { Intent } from '@sodax/sdk';
-
-const { mutateAsync: createLimitOrder } = useCreateLimitOrder();
-const { mutateAsync: cancelLimitOrder } = useCancelLimitOrder();
-
-// Limit orders have no deadline, must be cancelled manually.
-// `useCancelLimitOrder` TVars are FLAT: `{ srcChainKey, intent, walletProvider }` (no `params` wrapper).
-async function flow(intent: Intent) {
-  if (!walletProvider) return;
-  await createLimitOrder({ params: limitOrderParams, walletProvider });
-  await cancelLimitOrder({ srcChainKey, intent, walletProvider });
-}
-```
-
-## Customize TanStack Query behavior
-
-Every mutation hook accepts an optional `mutationOptions` slot for consumers to override TanStack Query knobs (`retry`, `onError`, `mutationKey`, etc.). The hook's `mutationFn` throws on SDK failure (so `mutation.error`, `onError`, and `retry` engage natively); its own `onSuccess` invalidations run first on real success, then the consumer's `onSuccess` is awaited.
-
-```tsx
-import { useSwap } from '@sodax/dapp-kit';
-import { useIsMutating } from '@tanstack/react-query';
-
-const { mutateAsync: swap, isError, error } = useSwap({
-  mutationOptions: {
-    retry: 5,
-    onError: err => toast.error(err.message),
-    onSuccess: swapResponse => {
-      // Runs AFTER dapp-kit's xBalances invalidations — only on confirmed success.
-      trackSwap(swapResponse);
-    },
-  },
-});
-
-// Track in-flight swaps anywhere in the app via the default mutationKey
-const swapsInFlight = useIsMutating({ mutationKey: ['swap'] });
-console.log({ swap, isError, error, swapsInFlight });
-```
-
-## Gotchas
-
-### Token list has duplicate addresses
-
-`getSupportedSolverTokens()` can return multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
-
-### Balance display
-
-Balances come from `@sodax/wallet-sdk-react`, not from dapp-kit. See `wallet-connectivity.md` for `useXBalances`.
-
-## Types
-
-```typescript
-type CreateIntentParams = {
-  inputToken: string;
-  outputToken: string;
-  inputAmount: bigint;
-  minOutputAmount: bigint;
-  deadline: bigint;            // 0n = no deadline
-  allowPartialFill: boolean;
-  srcChain: SpokeChainId;
-  dstChain: SpokeChainId;
-  srcAddress: string;
-  dstAddress: string;
-  solver: Address;             // address(0) = any solver
-  data: Hex;
-};
-```