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

package/ai-exported/integration/quickstart.md

@@ -1,187 +0,0 @@
-# Quickstart — `@sodax/dapp-kit` v2
-
-Get a React app running with dapp-kit in five minutes. For copy-paste recipes per feature, see [`recipes/`](recipes/). For design rationale, see [`architecture.md`](architecture.md).
-
-## 1. Install
-
-```bash
-# Required
-pnpm add @sodax/dapp-kit @tanstack/react-query
-
-# Wallet connectivity (the canonical companion)
-pnpm add @sodax/wallet-sdk-react
-```
-
-`@sodax/dapp-kit` peers on `react`, `react-dom` (>=18), and `@tanstack/react-query`. It re-exports `@sodax/sdk` — don't add `@sodax/types` separately.
-
-## 2. Wire providers
-
-```tsx
-// 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://mainnet.base.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://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` gives you a `QueryClient` pre-wired with global mutation observability. Optional — if you construct your own `QueryClient`, nothing changes. See [`recipes/observability.md`](recipes/observability.md).
-
-## 3. Initialize the SDK (optional)
-
-For the latest tokens / chains / fee parameters from the backend:
-
-```tsx
-import { useEffect } from 'react';
-import { useSodaxContext } from '@sodax/dapp-kit';
-
-export function useInitializeSodax() {
-  const { sodax } = useSodaxContext();
-  useEffect(() => {
-    sodax.config.initialize().then((result) => {
-      if (!result.ok) console.error('Failed to initialize Sodax:', result.error);
-    });
-  }, [sodax]);
-}
-```
-
-Skipping this works — feature services fall back to packaged defaults — but you'll miss tokens / chains added after the SDK release.
-
-## 4. Get a wallet provider
-
-```tsx
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function MyFeature() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BSC_MAINNET });
-  // undefined until the user connects a BSC wallet
-  return <button disabled={!walletProvider}>...</button>;
-}
-```
-
-`useWalletProvider` returns a chain-specific wallet provider object that satisfies `IEvmWalletProvider` (or `IIconWalletProvider`, `ISolanaWalletProvider`, etc., depending on the chain).
-
-## 5. Run a mutation
-
-The canonical pattern: hook takes `{ mutationOptions }` (optional); domain inputs flow through `mutate(vars)`. Use `mutateAsyncSafe` for explicit `Result<T>` branching:
-
-```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 { 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>
-  );
-}
-```
-
-The exact same pattern works for every mutation: `useBridge`, `useSupply`, `useStake`, `useDexDeposit`, etc. The only difference is the `params` shape (each feature's reference doc has the type signature).
-
-## 6. Run a query
-
-Queries take `{ params, queryOptions }`. The hook owns `queryKey`, `queryFn`, and `enabled`:
-
-```tsx
-import { useQuote } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/sdk';
-
-function SwapQuote({ amount }: { amount: bigint }) {
-  const { data: quoteResult, isLoading } = useQuote({
-    params: {
-      payload: amount > 0n
-        ? {
-            token_src: '0x0000000000000000000000000000000000000000',
-            token_dst: '0x0000000000000000000000000000000000000000',
-            token_src_blockchain_id: ChainKeys.BSC_MAINNET,
-            token_dst_blockchain_id: ChainKeys.ARBITRUM_MAINNET,
-            amount,
-            quote_type: 'exact_input',
-          }
-        : undefined,
-    },
-    queryOptions: { staleTime: 3000 },
-  });
-
-  if (isLoading) return <p>Loading...</p>;
-  if (quoteResult?.ok) return <p>Output: {quoteResult.value.quoted_amount}</p>;
-  return null;
-}
-```
-
-Some query hooks return `Result<T>` as their `data` (the underlying SDK method returns Result and we surface it directly for query hooks; only mutations unwrap). Always check `.ok` before reading `.value`.
-
-## First-time troubleshooting
-
-| Error | Why | Fix |
-|---|---|---|
-| `Module '"@sodax/dapp-kit"' has no exported member 'useSpokeProvider'` | v1 hook deleted in v2. | Drop the import. Pass `walletProvider` (from `useWalletProvider`) into `mutate(vars)` instead. |
-| `Property 'approve' does not exist on type 'SafeUseMutationResult'` | v1 approve hooks returned `{ approve, isLoading, error }`; v2 returns `SafeUseMutationResult`. | Use `mutateAsync` / `mutateAsyncSafe`. `isLoading` → `isPending`. |
-| `Type 'CreateIntentParams' is missing the following properties from ...: walletProvider` | v1 hooks took params at hook-init; v2 takes them via `mutate(vars)`. | Move `params` and `walletProvider` from hook init to `mutate({ params, walletProvider })`. |
-| `Property 'xChainId' does not exist on type 'XToken'` | SDK-leakage rename: `xChainId` → `chainKey` on `XToken` in v2. | Use `xToken.chainKey`. (Note: `useXBalances` params still use `xChainId` for the request shape — that's distinct from the read shape.) |
-| `Type ... is missing the following properties from type 'MoneyMarketSupplyParams': srcChainKey, srcAddress` | SDK-leakage: v2 added required `srcChainKey` + `srcAddress` to action params. | Add both to your `params` payload. See [`features/money-market.md`](features/money-market.md). |
-| `Cannot read properties of undefined (reading 'sodax')` | `useSodaxContext` (or any dapp-kit hook) called outside `<SodaxProvider>`. | Wrap your component tree in `<SodaxProvider>` from this package. |
-
-For broader v1 → v2 migration, see [`../migration/README.md`](../migration/README.md).
-
-## What to read next
-
-- [`recipes/`](recipes/) — copy-paste patterns for each feature and cross-cutting concerns.
-- [`architecture.md`](architecture.md) — full design rationale for `useSafeMutation`, `unwrapResult`, queryKey conventions, etc.
-- [`features/<x>.md`](features/) — per-feature reference (hook tables, types, gotchas).
-- [`reference/hooks-index.md`](reference/hooks-index.md) — full hook table.
-- [`ai-rules.md`](ai-rules.md) — DO / DO NOT for AI agents writing dapp-kit code.
-
-## Cross-references
-
-- [`../../../sdk/ai-exported/AGENTS.md`](../../../sdk/ai-exported/AGENTS.md) — the underlying Core SDK's tree (resolves correctly in `node_modules/@sodax/`-layout). Useful when you hit SDK-level types or behaviors leaking through hook signatures.

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

@@ -1,136 +0,0 @@
-# Recipes — `@sodax/dapp-kit`
-
-Copy-paste patterns for adding SODAX features to a React app. Each recipe is self-contained and shows the canonical v2 hook shape (single-object params, `mutateAsyncSafe` for imperative flows, `Result<T>` handling).
-
-## Reading order
-
-1. **[`setup.md`](setup.md)** — Install packages, wire `SodaxProvider` + `QueryClientProvider`, optional `createSodaxQueryClient` for global mutation observability.
-2. **[`wallet-connectivity.md`](wallet-connectivity.md)** — Connect wallets via `@sodax/wallet-sdk-react`, get a typed `walletProvider` per chain, fetch token balances.
-3. Pick a feature recipe — each one is independent of the others.
-
-## Index
-
-### Foundation
-
-| Recipe | Purpose |
-|---|---|
-| [`setup.md`](setup.md) | Install packages, wire providers, optional `createSodaxQueryClient` |
-| [`wallet-connectivity.md`](wallet-connectivity.md) | Wallet connection, `useWalletProvider`, balance hooks |
-
-### Cross-cutting patterns
-
-| Recipe | Purpose |
-|---|---|
-| [`mutation-error-handling.md`](mutation-error-handling.md) | Pick between `mutate` / `mutateAsync` / `mutateAsyncSafe` |
-| [`observability.md`](observability.md) | Global mutation logging via `createSodaxQueryClient`, per-mutation `meta.silent` |
-| [`invalidations.md`](invalidations.md) | Hook-owned invalidations and how to compose your own `onSuccess` |
-
-### Per-feature
-
-| Recipe | Hooks covered |
-|---|---|
-| [`swap.md`](swap.md) | `useQuote`, `useSwap`, `useSwapAllowance`, `useSwapApprove`, limit orders |
-| [`bridge.md`](bridge.md) | `useBridge`, allowance/approval, bridgeable amounts/tokens |
-| [`money-market.md`](money-market.md) | `useSupply`, `useBorrow`, `useWithdraw`, `useRepay`, reserves data |
-| [`staking.md`](staking.md) | `useStake`, `useUnstake`, `useClaim`, staking info, ratios |
-| [`migration.md`](migration.md) | `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln` |
-| [`dex.md`](dex.md) | `useDexDeposit`, `useSupplyLiquidity`, positions, pools |
-| [`bitcoin.md`](bitcoin.md) | `useRadfiSession`, `useFundTradingWallet`, `useRadfiWithdraw`, UTXO management |
-| [`backend-queries.md`](backend-queries.md) | Intent tracking, orderbook, money market position queries (read-only, no wallet) |
-
-## Hook conventions (mandatory)
-
-These rules are enforced across every dapp-kit hook by [`packages/dapp-kit/src/hooks/_mutationContract.test.ts`](../../../src/hooks/_mutationContract.test.ts) and apply to everything you write against this package.
-
-### Single-object params
-
-```tsx
-import { useSwap, useSwapAllowance } from '@sodax/dapp-kit';
-import { ChainKeys } from '@sodax/sdk';
-
-// Query hooks — { params, queryOptions }
-// Note: many query hooks wrap the SDK request under `params.payload`; some nest sibling
-// fields like `walletProvider` or `srcChainKey` under `params` alongside `payload`.
-// `useSwapAllowance` is one such hook — see features/swap.md for the canonical shape.
-const { data: isApproved } = useSwapAllowance({
-  params: { payload: intentParams, srcChainKey: ChainKeys.BSC_MAINNET, walletProvider },
-});
-
-// Mutation hooks — hook takes only mutationOptions; domain inputs flow through mutate(vars)
-const { mutateAsync: swap } = useSwap();
-async function runSwap() {
-  if (!walletProvider) return;
-  await swap({ params: intentParams, walletProvider });
-}
-```
-
-No positional args. No `spokeProvider` at the hook level (that was v1; deleted in v2). All domain inputs (`params`, `walletProvider`, per-call config) flow through `mutate(vars)` for mutations and through `params` for queries.
-
-### `mutateAsyncSafe`
-
-Every mutation hook returns three call shapes. `mutateAsyncSafe` is the recommended default for sequenced flows — it returns `Promise<Result<TData>>` and never rejects:
-
-```tsx
-import { useSwap } from '@sodax/dapp-kit';
-
-const { mutateAsyncSafe: swap } = useSwap();
-async function runSwap() {
-  if (!walletProvider) return;
-  const result = await swap({ params: intentParams, walletProvider });
-  if (!result.ok) { toast.error(result.error instanceof Error ? result.error.message : 'failed'); return; }
-  const { intent } = result.value;
-  console.log(intent);
-}
-```
-
-Full comparison in [`mutation-error-handling.md`](mutation-error-handling.md).
-
-### `queryOptions`
-
-All query hooks accept optional `queryOptions` to override React Query defaults. The hook owns `queryKey`, `queryFn`, and `enabled` — those are not consumer-overridable.
-
-```tsx
-import { useQuote } from '@sodax/dapp-kit';
-
-// `useQuote` wraps the SDK request under `params.payload` — don't pass the SDK request
-// directly under `params`. `payload` here is a `SolverIntentQuoteRequest`.
-const { data } = useQuote({
-  params: { payload },
-  queryOptions: { staleTime: 5000, refetchInterval: 10000 },
-});
-```
-
-### `Result<T>` in query hooks
-
-Some query hooks return `Result<T>` as their `data` (the underlying SDK method can fail). Always check `.ok` before accessing `.value`:
-
-```tsx
-import { useQuote } from '@sodax/dapp-kit';
-
-// useQuote nests the SDK request under params.payload. `payload` here is a `SolverIntentQuoteRequest`.
-const { data: quoteResult } = useQuote({ params: { payload } });
-if (quoteResult?.ok) {
-  const quote = quoteResult.value;
-  console.log(quote);
-} else {
-  console.error(quoteResult?.error);
-}
-```
-
-### `bigint` for amounts
-
-Token amounts are `bigint` scaled by decimals. Use `viem`'s `parseUnits` / `formatUnits`:
-
-```tsx
-import { parseUnits, formatUnits } from 'viem';
-const amount = parseUnits('1.5', 18);   // 1500000000000000000n
-const display = formatUnits(amount, 18); // '1.5'
-```
-
-## Backend / non-React consumers
-
-If you're building a backend (API server, bot, script), you don't need `@sodax/dapp-kit` at all — use `@sodax/sdk` directly. The SDK has its own AI-agent docs at `node_modules/@sodax/sdk/ai-exported/AGENTS.md`.
-
-## Migration pointer
-
-If you're porting v1 dapp-kit code to v2, start at [`../../migration/README.md`](../../migration/README.md). It covers: hook signatures (single-arg policy), `Result<T>` handling shift, deleted `useSpokeProvider`, queryKey conventions, and SDK leakage.

package/ai-exported/integration/recipes/backend-queries.md

@@ -1,157 +0,0 @@
-# Recipe: Backend Queries
-
-Read-only data hooks. No wallet connection required.
-
-**Depends on:** [setup.md](setup.md)
-
-## Hooks
-
-### Intents
-
-| Hook | Purpose |
-|------|---------|
-| `useBackendIntentByTxHash` | Intent by hub chain tx hash (polls 1s) |
-| `useBackendIntentByHash` | Intent by intent hash |
-| `useBackendUserIntents` | All intents for a user with date filtering |
-
-### Orderbook
-
-| Hook | Purpose |
-|------|---------|
-| `useBackendOrderbook` | Solver orderbook with pagination (cached 30s, no auto-refetch) |
-
-### Money Market
-
-| Hook | Purpose |
-|------|---------|
-| `useBackendMoneyMarketPosition` | User's money market position |
-| `useBackendMoneyMarketAsset` | Specific asset details |
-| `useBackendAllMoneyMarketAssets` | All money market assets |
-| `useBackendMoneyMarketAssetSuppliers` | Suppliers for an asset |
-| `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
-| `useBackendAllMoneyMarketBorrowers` | All borrowers |
-
-### Swap Submission
-
-| Hook | Purpose |
-|------|---------|
-| `useBackendSubmitSwapTx` | Submit swap tx to backend |
-| `useBackendSubmitSwapTxStatus` | Check submitted swap status |
-
-## Track Intent
-
-```tsx
-import { useBackendIntentByTxHash } from '@sodax/dapp-kit';
-
-function IntentTracker({ txHash }: { txHash: string }) {
-  const { data: intent, isLoading } = useBackendIntentByTxHash({
-    params: { txHash },
-  });
-
-  if (isLoading) return <div>Loading...</div>;
-  return <pre>{JSON.stringify(intent, null, 2)}</pre>;
-}
-```
-
-## User Intent History
-
-```tsx
-import { useBackendUserIntents } from '@sodax/dapp-kit';
-
-function IntentHistory({ userAddress }: { userAddress: `0x${string}` }) {
-  const { data: intents } = useBackendUserIntents({
-    params: {
-      userAddress,
-      startDate: Date.now() - 7 * 24 * 60 * 60 * 1000,
-      endDate: Date.now(),
-    },
-  });
-
-  return (
-    <div>
-      {intents?.items.map((intent, i) => (
-        <div key={i}>
-          <p>{intent.intentHash} -- {intent.open ? 'open' : 'closed'}</p>
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-## Orderbook
-
-```tsx
-import { useBackendOrderbook } from '@sodax/dapp-kit';
-
-function Orderbook() {
-  // `pagination` is nested under `params` per the canonical query-hook shape.
-  const { data: orderbook } = useBackendOrderbook({
-    params: { pagination: { offset: '0', limit: '20' } },
-  });
-  return <pre>{JSON.stringify(orderbook, null, 2)}</pre>;
-}
-```
-
-## Money Market Dashboard
-
-```tsx
-// @ai-snippets-skip — uses example field name supplyAPY not in MoneyMarketAsset type
-import { useBackendMoneyMarketPosition, useBackendAllMoneyMarketAssets } from '@sodax/dapp-kit';
-
-function MMDashboard({ userAddress }: { userAddress: string }) {
-  const { data: position } = useBackendMoneyMarketPosition({ params: { userAddress } });
-  const { data: assets } = useBackendAllMoneyMarketAssets({});
-
-  return (
-    <div>
-      {position && <pre>{JSON.stringify(position, null, 2)}</pre>}
-      {assets?.map((a, i) => <p key={i}>{a.symbol}: Supply {a.supplyAPY}%</p>)}
-    </div>
-  );
-}
-```
-
-## Custom Query Options
-
-All read hooks accept `queryOptions` to override defaults:
-
-```tsx
-// @ai-snippets-skip
-const { data } = useBackendIntentByTxHash({
-  params: { txHash },
-  queryOptions: { staleTime: 5000, refetchInterval: 2000, retry: 3 },
-});
-```
-
-## Submit a Swap Tx
-
-`useBackendSubmitSwapTx` is a mutation hook. Per-call config (e.g. backend base URL) flows through `mutate(vars)`; TanStack Query knobs flow through the optional `mutationOptions` slot:
-
-```tsx
-import { useBackendSubmitSwapTx } from '@sodax/dapp-kit';
-
-function SubmitButton({ swapPayload, baseURL }) {
-  const { mutateAsync: submitSwapTx, isPending } = useBackendSubmitSwapTx({
-    mutationOptions: { retry: 5 }, // overrides default retry: 3
-  });
-
-  const handleSubmit = async () => {
-    const response = await submitSwapTx({
-      request: swapPayload,
-      apiConfig: { baseURL }, // per-call backend override
-    });
-    console.log('Submitted:', response);
-  };
-
-  return <button onClick={handleSubmit} disabled={isPending}>Submit</button>;
-}
-```
-
-## Default Polling
-
-| Hook | Interval |
-|------|---------|
-| `useBackendIntentByTxHash` | 1s |
-| `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
-| Others | No auto-refresh |

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

@@ -1,193 +0,0 @@
-# Recipe: Bitcoin (Radfi)
-
-Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
-
-**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
-
-## Hooks
-
-### Session
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useRadfiAuth` | Mutation | Authenticate with Radfi via BIP322 signing |
-| `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
-| `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
-
-### Balance
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useBitcoinBalance` | Query | BTC balance for any address (sums UTXOs from mempool.space) |
-| `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API (confirmed + pending) |
-
-### Operations
-
-| Hook | Type | Purpose |
-|------|------|---------|
-| `useFundTradingWallet` | Mutation | Send BTC from personal wallet to trading wallet |
-| `useRadfiWithdraw` | Mutation | Withdraw BTC from trading wallet to personal wallet |
-| `useExpiredUtxos` | Query | Fetch UTXOs that need renewal (polls every 60s) |
-| `useRenewUtxos` | Mutation | Renew expired UTXOs in trading wallet |
-
-## Session Flow
-
-Radfi requires authentication before any trading operation. The typical flow:
-
-```tsx
-import { useRadfiSession } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function BitcoinAuth() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-  const { isAuthed, tradingAddress, login, isLoginPending } = useRadfiSession(walletProvider);
-
-  if (isAuthed) {
-    return <p>Authenticated. Trading wallet: {tradingAddress}</p>;
-  }
-
-  return (
-    <button onClick={login} disabled={isLoginPending}>
-      {isLoginPending ? 'Signing...' : 'Login to Radfi'}
-    </button>
-  );
-}
-```
-
-`useRadfiSession` handles the full lifecycle:
-- On mount: refreshes token to validate existing session
-- Every 5 min: auto-refreshes access token
-- If refresh fails: clears session, sets `isAuthed = false`
-- Session persisted in localStorage (keyed by wallet address)
-
-## Check Balances
-
-```tsx
-import { useBitcoinBalance, useTradingWalletBalance, useTradingWallet } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-  const { tradingAddress } = useTradingWallet(walletAddress);
-
-  // Personal wallet balance (from mempool.space)
-  const { data: personalBalance } = useBitcoinBalance({
-    params: { address: walletAddress },
-  });
-
-  // Trading wallet balance (from Radfi API). `RadfiWalletBalance` fields:
-  // `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
-  const { data: tradingBalance } = useTradingWalletBalance({
-    params: { walletProvider, tradingAddress },
-  });
-
-  return (
-    <div>
-      <p>Personal: {personalBalance?.toString() ?? '...'} sats</p>
-      <p>Trading: {tradingBalance?.btcSatoshi?.toString() ?? '...'} sats</p>
-    </div>
-  );
-}
-```
-
-## Fund Trading Wallet
-
-```tsx
-import { useFundTradingWallet } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function FundButton() {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-  const { mutateAsyncSafe: fundWallet, isPending } = useFundTradingWallet();
-
-  const handleFund = async () => {
-    if (!walletProvider) return;
-    const result = await fundWallet({ amount: 100_000n, walletProvider }); // 100,000 satoshis
-    if (result.ok) console.log('Funded:', result.value);
-    else console.error('Fund failed:', result.error);
-  };
-
-  return (
-    <button onClick={handleFund} disabled={isPending || !walletProvider}>
-      {isPending ? 'Funding...' : 'Fund Trading Wallet'}
-    </button>
-  );
-}
-```
-
-## Withdraw from Trading Wallet
-
-```tsx
-import { useRadfiWithdraw } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function WithdrawButton({ withdrawTo }: { withdrawTo: string }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-  const { mutateAsync: withdraw, isPending } = useRadfiWithdraw();
-
-  const handleWithdraw = async () => {
-    if (!walletProvider) return;
-    const result = await withdraw({
-      amount: '10000',
-      tokenId: '0:0',
-      withdrawTo, // user's personal BTC address
-      walletProvider,
-    });
-    console.log('Withdrawn:', result.txId, 'Fee:', result.fee);
-  };
-
-  return (
-    <button onClick={handleWithdraw} disabled={isPending || !walletProvider}>
-      {isPending ? 'Withdrawing...' : 'Withdraw'}
-    </button>
-  );
-}
-```
-
-## Manage Expired UTXOs
-
-UTXOs in the trading wallet can expire. Check and renew them:
-
-```tsx
-import { useExpiredUtxos, useRenewUtxos } from '@sodax/dapp-kit';
-import { useWalletProvider } from '@sodax/wallet-sdk-react';
-import { ChainKeys } from '@sodax/sdk';
-
-function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
-  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET });
-  const { data: expiredUtxos } = useExpiredUtxos({
-    params: { walletProvider, tradingAddress },
-  });
-  const { mutateAsync: renewUtxos, isPending } = useRenewUtxos();
-
-  if (!expiredUtxos?.length) return <p>No expired UTXOs</p>;
-
-  const handleRenew = async () => {
-    if (!walletProvider) return;
-    const txIdVouts = expiredUtxos.map((u) => u.txidVout);
-    const txId = await renewUtxos({ txIdVouts, walletProvider });
-    console.log('Renewed:', txId);
-  };
-
-  return (
-    <div>
-      <p>{expiredUtxos.length} expired UTXOs</p>
-      <button onClick={handleRenew} disabled={isPending || !walletProvider}>
-        {isPending ? 'Renewing...' : 'Renew UTXOs'}
-      </button>
-    </div>
-  );
-}
-```
-
-## Notes
-
-- **Authentication required** before any trading operation. `useRadfiSession` manages this automatically.
-- **Trading wallet** is created during first authentication — not a separate step.
-- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Radfi session from localStorage.
-- **PSBT signing flow**: withdraw and renew operations build an unsigned PSBT server-side, user signs it locally, then submits back for co-signing and broadcast.
-- **Session tokens** are stored in localStorage keyed by wallet address. They're for API rate-limiting, not for accessing user assets.