@sodax/skills 2.0.0-rc.4

package/knowledge/dapp-kit/integration/recipes/README.md

@@ -0,0 +1,136 @@
+# 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 knowledge tree shipped via `@sodax/skills` — load the `sodax-sdk-integration` skill or read `node_modules/@sodax/skills/knowledge/sdk/AGENTS.md` directly.
+
+## 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/knowledge/dapp-kit/integration/recipes/backend-queries.md

@@ -0,0 +1,157 @@
+# 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/knowledge/dapp-kit/integration/recipes/bitcoin.md

@@ -0,0 +1,193 @@
+# 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.

package/knowledge/dapp-kit/integration/recipes/bridge.md

@@ -0,0 +1,174 @@
+# Recipe: Bridge
+
+Cross-chain token transfers via the hub-and-spoke vault architecture.
+
+**Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
+
+## Hooks
+
+| Hook | Type | Purpose |
+|------|------|---------|
+| `useBridge` | Mutation | Execute a cross-chain bridge transfer |
+| `useBridgeAllowance` | Query | Check if token approval is needed |
+| `useBridgeApprove` | Mutation | Approve tokens for bridge |
+| `useGetBridgeableAmount` | Query | Available bridgeable amount between two tokens |
+| `useGetBridgeableTokens` | Query | Tokens bridgeable to a destination chain |
+
+## Check Bridgeable Tokens
+
+```tsx
+import { useGetBridgeableTokens } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/sdk';
+
+function BridgeableTokensList() {
+  // `data` is `XToken[] | undefined` — the hook throws on SDK `!ok` so we get the unwrapped value.
+  const { data: tokens } = useGetBridgeableTokens({
+    params: { from: ChainKeys.BASE_MAINNET, to: ChainKeys.POLYGON_MAINNET, token: '0x0000000000000000000000000000000000000000' },
+  });
+
+  if (tokens) {
+    return <ul>{tokens.map((t) => <li key={t.address}>{t.symbol}</li>)}</ul>;
+  }
+  return null;
+}
+```
+
+## Check Allowance + Approve
+
+```tsx
+import { useBridgeAllowance, useBridgeApprove } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+import type { CreateBridgeIntentParams } from '@sodax/sdk';
+
+function BridgeApproval({ params }: { params: CreateBridgeIntentParams }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
+  // useBridgeAllowance wraps payload + walletProvider under params (not at top level).
+  const { data: isApproved } = useBridgeAllowance({
+    params: { payload: params, walletProvider },
+  });
+  const { mutateAsync: approve, isPending } = useBridgeApprove();
+
+  if (isApproved) return null;
+  return (
+    <button onClick={() => walletProvider && approve({ params, walletProvider })} disabled={isPending}>
+      {isPending ? 'Approving...' : 'Approve for Bridge'}
+    </button>
+  );
+}
+```
+
+## Execute Bridge
+
+```tsx
+import { useBridge } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/sdk';
+
+function BridgeButton({ srcAddress }: { srcAddress: `0x${string}` }) {
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
+  const { mutateAsync: bridge, isPending } = useBridge();
+
+  const handleBridge = async () => {
+    if (!walletProvider) return;
+    try {
+      const { srcChainTxHash, dstChainTxHash } = await bridge({
+        params: {
+          srcChainKey: ChainKeys.BASE_MAINNET,
+          srcAddress,
+          srcToken: '0x0000000000000000000000000000000000000000',
+          amount: 1000000000000000000n,
+          dstChainKey: ChainKeys.POLYGON_MAINNET,
+          dstToken: '0x0000000000000000000000000000000000000000',
+          recipient: '0x0000000000000000000000000000000000000000',
+        },
+        walletProvider,
+      });
+      console.log('Bridge successful:', { srcChainTxHash, dstChainTxHash });
+    } catch (e) {
+      console.error(e);
+    }
+  };
+
+  return (
+    <button onClick={handleBridge} disabled={isPending}>
+      {isPending ? 'Bridging...' : 'Bridge'}
+    </button>
+  );
+}
+```
+
+## Full Example
+
+```tsx
+import { useState } from 'react';
+import { useBridge, useBridgeAllowance, useBridgeApprove, useGetBridgeableAmount } from '@sodax/dapp-kit';
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys, type XToken } from '@sodax/sdk';
+import type { CreateBridgeIntentParams } from '@sodax/sdk';
+import { parseUnits, formatUnits } from 'viem';
+
+export function BridgePage({ srcXToken, dstXToken, srcAddress }: { srcXToken: XToken; dstXToken: XToken; srcAddress: `0x${string}` }) {
+  const [amount, setAmount] = useState('');
+  const walletProvider = useWalletProvider({ xChainId: ChainKeys.BASE_MAINNET });
+  const parsedAmount = amount ? parseUnits(amount, 6) : 0n;
+
+  const bridgeParams: CreateBridgeIntentParams<typeof ChainKeys.BASE_MAINNET> | undefined = parsedAmount > 0n
+    ? {
+        srcChainKey: ChainKeys.BASE_MAINNET,
+        srcAddress,
+        srcToken: srcXToken.address,
+        amount: parsedAmount,
+        dstChainKey: ChainKeys.POLYGON_MAINNET,
+        dstToken: dstXToken.address,
+        recipient: '0x0000000000000000000000000000000000000000',
+      }
+    : undefined;
+
+  // useGetBridgeableAmount in v2 takes a pair of XToken objects (each carries chainKey).
+  // `data` is `BridgeLimit | undefined` (already unwrapped; hook throws on SDK !ok).
+  const { data: bridgeableAmount } = useGetBridgeableAmount({
+    params: { from: srcXToken, to: dstXToken },
+  });
+  const { data: isApproved } = useBridgeAllowance({
+    params: bridgeParams ? { payload: bridgeParams, walletProvider } : undefined,
+  });
+  const { mutateAsyncSafe: approve, isPending: isApproving } = useBridgeApprove();
+  const { mutateAsyncSafe: bridge, isPending: isBridging } = useBridge();
+
+  const handleBridge = async () => {
+    if (!bridgeParams || !walletProvider) return;
+    if (!isApproved) {
+      const r = await approve({ params: bridgeParams, walletProvider });
+      if (!r.ok) { alert(r.error instanceof Error ? r.error.message : 'Approve failed'); return; }
+    }
+    const r = await bridge({ params: bridgeParams, walletProvider });
+    if (r.ok) alert(`Bridge complete! src=${r.value.srcChainTxHash}`);
+    else alert(r.error instanceof Error ? r.error.message : 'Bridge failed');
+  };
+
+  return (
+    <div>
+      <input placeholder="Amount" value={amount} onChange={(e) => setAmount(e.target.value)} />
+      {bridgeableAmount && <p>Max: {formatUnits(bridgeableAmount.amount, bridgeableAmount.decimals)}</p>}
+      <button onClick={handleBridge} disabled={isBridging || isApproving || !bridgeParams || !walletProvider}>
+        {isApproving ? 'Approving...' : isBridging ? 'Bridging...' : 'Bridge'}
+      </button>
+    </div>
+  );
+}
+```
+
+## Types
+
+```typescript
+type CreateBridgeIntentParams<K extends SpokeChainKey = SpokeChainKey> = {
+  srcChainKey: K;
+  srcAddress: string;
+  srcToken: string;
+  amount: bigint;
+  dstChainKey: SpokeChainKey;
+  dstToken: string;
+  recipient: string;   // non-encoded recipient address on the destination chain
+};
+```