@sodax/skills 2.0.0-rc.10 → 2.0.0-rc.12

package/.claude-plugin/plugin.json

@@ -12,7 +12,30 @@
     "./skills/sodax-sdk/recovery",
     "./skills/sodax-sdk/backend-api",
     "./skills/sodax-wallet-sdk-core",
+    "./skills/sodax-wallet-sdk-core/evm",
+    "./skills/sodax-wallet-sdk-core/solana",
+    "./skills/sodax-wallet-sdk-core/sui",
+    "./skills/sodax-wallet-sdk-core/bitcoin",
+    "./skills/sodax-wallet-sdk-core/stellar",
+    "./skills/sodax-wallet-sdk-core/icon",
+    "./skills/sodax-wallet-sdk-core/injective",
+    "./skills/sodax-wallet-sdk-core/near",
+    "./skills/sodax-wallet-sdk-core/stacks",
     "./skills/sodax-wallet-sdk-react",
-    "./skills/sodax-dapp-kit"
+    "./skills/sodax-wallet-sdk-react/connect",
+    "./skills/sodax-wallet-sdk-react/wallet-modal",
+    "./skills/sodax-wallet-sdk-react/bridge-to-sdk",
+    "./skills/sodax-wallet-sdk-react/switch-chain",
+    "./skills/sodax-wallet-sdk-react/sign-message",
+    "./skills/sodax-wallet-sdk-react/walletconnect",
+    "./skills/sodax-dapp-kit",
+    "./skills/sodax-dapp-kit/swap",
+    "./skills/sodax-dapp-kit/money-market",
+    "./skills/sodax-dapp-kit/staking",
+    "./skills/sodax-dapp-kit/bridge",
+    "./skills/sodax-dapp-kit/dex",
+    "./skills/sodax-dapp-kit/migration",
+    "./skills/sodax-dapp-kit/bitcoin",
+    "./skills/sodax-dapp-kit/auxiliary-services"
   ]
 }

package/AGENTS.md

@@ -4,16 +4,16 @@
 
 ## What's here
 
-This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular per-feature skills** under `sodax-sdk` (one per Core SDK feature service). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
+This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular skills** under every broad skill: `sodax-sdk` (one per Core SDK feature service), `sodax-dapp-kit` (one per dapp-kit feature domain), `sodax-wallet-sdk-core` (one per chain family), and `sodax-wallet-sdk-react` (one per connectivity concern). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
 
 | SDK package | Broad skill | Granular per-feature skills |
 |---|---|---|
 | `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
-| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | — |
-| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | — |
-| `@sodax/dapp-kit` | `sodax-dapp-kit` | — |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | `sodax-wallet-sdk-core/evm`, `sodax-wallet-sdk-core/solana`, `sodax-wallet-sdk-core/sui`, `sodax-wallet-sdk-core/bitcoin`, `sodax-wallet-sdk-core/stellar`, `sodax-wallet-sdk-core/icon`, `sodax-wallet-sdk-core/injective`, `sodax-wallet-sdk-core/near`, `sodax-wallet-sdk-core/stacks` |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | `sodax-wallet-sdk-react/connect`, `sodax-wallet-sdk-react/wallet-modal`, `sodax-wallet-sdk-react/bridge-to-sdk`, `sodax-wallet-sdk-react/switch-chain`, `sodax-wallet-sdk-react/sign-message`, `sodax-wallet-sdk-react/walletconnect` |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` | `sodax-dapp-kit/swap`, `sodax-dapp-kit/money-market`, `sodax-dapp-kit/staking`, `sodax-dapp-kit/bridge`, `sodax-dapp-kit/dex`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
 
-**When to prefer a granular skill:** if the consumer has already picked a feature (e.g. *"swap with Sodax"*, *"supply on money market"*), load the matching granular skill — it's ~3 KB vs `sodax-sdk`'s ~13 KB and points at exactly the knowledge files needed for that feature. Load the broad `sodax-sdk` skill when the feature is undecided, the task spans multiple features, or the consumer is porting a full v1 codebase.
+**When to prefer a granular skill:** if the consumer has already picked a sub-domain (e.g. *"swap with Sodax"*, *"supply on money market"*, *"useSwap hook"*, *"instantiate EvmWalletProvider"*, *"add a connect button"*), load the matching granular skill — it's ~3 KB vs the broad skill's ~13 KB and points at exactly the knowledge files needed. For a React dapp that has settled on one feature, load `sodax-dapp-kit/<feature>`; for raw SDK / backend work, load `sodax-sdk/<feature>`; for a known chain in a backend/Node wallet flow, load `sodax-wallet-sdk-core/<chain>`; for a known React wallet concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect), load `sodax-wallet-sdk-react/<concern>`. Load the broad skill when the sub-domain is undecided, the task spans several, or the consumer is porting a full v1 codebase.
 
 > **What about `@sodax/types`?** No skill. The package has no consumer-facing surface — it's pure TypeScript types, re-exported through `@sodax/sdk`. Importing `@sodax/types` directly invites version skew. The SDK skills cover all `@sodax/types` symbols you need.
 
@@ -24,6 +24,9 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
 | Consumer is… | Load skills (mode) |
 |---|---|
 | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
+| **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, migration, bitcoin, auxiliary-services) | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit/<feature>` (granular, covers both modes via internal links). Skip the broad `sodax-dapp-kit` skill. If the wallet concern is also settled (just a connect button, modal, bridge, etc.), narrow to `sodax-wallet-sdk-react/<concern>` too |
+| **Scaffolding ONE chain's wallet provider** (backend/Node/non-React: evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks) | `sodax-wallet-sdk-core/<chain>` (granular, covers both modes) → `sodax-sdk/<feature>` for the operation it signs. Skip the broad `sodax-wallet-sdk-core` skill |
+| **Scaffolding ONE React wallet concern** (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect) | `sodax-wallet-sdk-react/<concern>` (granular, covers both modes). Skip the broad `sodax-wallet-sdk-react` skill |
 | **Building a NEW React dapp** | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit` (integration) → (`sodax-sdk` (integration) only if dropping below dapp-kit) |
 | **Building a NEW React app, no dapp-kit** (calling the SDK directly) | `sodax-wallet-sdk-react` (integration) → `sodax-sdk` (integration) |
 | **Building a NEW Node / backend service or script** | `sodax-sdk` (integration) → `sodax-wallet-sdk-core` (integration; only if it signs) |
@@ -57,9 +60,16 @@ packages/skills/
     ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
     │                                       <feature>/SKILL.md ×9 — swap, money-market, bridge, staking, dex,
     │                                       migration, partner, recovery, backend-api}
-    ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
-    ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/ — incl. 4 .tsx example apps under integration/knowledge/examples/}
-    └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
+    ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+    │                                       <chain>/SKILL.md ×9 — evm, solana, sui, bitcoin, stellar, icon,
+    │                                       injective, near, stacks}
+    ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/
+    │                                       (incl. 4 .tsx example apps under integration/knowledge/examples/),
+    │                                       <concern>/SKILL.md ×6 — connect, wallet-modal, bridge-to-sdk,
+    │                                       switch-chain, sign-message, walletconnect}
+    └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+                                            <feature>/SKILL.md ×8 — swap, money-market, staking, bridge, dex,
+                                            migration, bitcoin, auxiliary-services}
 ```
 
 Each `<mode>/knowledge/` subtree contains `ai-rules.md`, `quickstart.md`, `architecture.md`, `features/`, `recipes/`, `reference/`, and `chain-specifics.md` / `breaking-changes/` where applicable.

package/README.md

@@ -22,6 +22,7 @@ Four mode-gated skills land in your repo (under `.claude/skills/` or wherever th
 | Bundle | Contains |
 |---|---|
 | **4 mode-gated skills** under `skills/sodax-<pkg>/SKILL.md` | One skill per SODAX SDK package. `<pkg>` ∈ `sdk`, `wallet-sdk-core`, `wallet-sdk-react`, `dapp-kit`. Each SKILL.md gates by mode (integration vs migration) at the top of the body. |
+| **Granular skills** under `skills/sodax-<pkg>/<sub-domain>/SKILL.md` | Every broad skill ships focused single-domain children: `sodax-sdk` / `sodax-dapp-kit` per feature (swap, money-market, bridge, staking, dex, …); `sodax-wallet-sdk-core` per chain (evm, solana, sui, bitcoin, stellar, icon, injective, near, stacks); `sodax-wallet-sdk-react` per connectivity concern (connect, wallet-modal, bridge-to-sdk, switch-chain, sign-message, walletconnect). Load one when the task is already scoped to a single sub-domain — it points at exactly the knowledge files for it instead of the whole broad skill. |
 | **Knowledge** under `skills/sodax-<pkg>/{integration,migration-v1-to-v2}/knowledge/` | Long-form supporting docs — features, recipes, reference tables, breaking-change writeups, code examples. Each skill ships both mode subtrees so `npx skills add` copies the full reference together. |
 | **`AGENTS.md`** at the package root | Tool-neutral router: maps the consumer's stated task to the right skill + mode. |
 

package/package.json

@@ -4,7 +4,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "2.0.0-rc.10",
+  "version": "2.0.0-rc.12",
   "license": "MIT",
   "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
   "keywords": [

package/skills/sodax-dapp-kit/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: sodax-dapp-kit
-description: 'INTEGRATION (write NEW code) — @sodax/dapp-kit is React hooks wrapping @sodax/sdk with React Query across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Radfi, backend queries, shared). React-only — Node and backend code uses `@sodax/sdk` directly. Use whenever a React dapp needs SODAX feature hooks. Triggers on "use @sodax/dapp-kit", "useSwap", "useMoneyMarket", "useStake", "useBridge", "useDex", "useMigrate", any `use<Feature>` hook name from dapp-kit, "Sodax React hooks", "dapp-kit query / mutation". v2 hook shape: mutation hooks return `SafeUseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>`. mutationFn unwraps SDK Result<T> and throws on `!ok` so React Query''s native error model engages. Hook-owned invalidations — consumer onSuccess runs after. MIGRATION (port v1 → v2) — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed", v1 fingerprints (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Load this skill if EITHER applies; the body gates by mode.'
+description: 'INTEGRATION (write NEW code) — @sodax/dapp-kit is React hooks wrapping @sodax/sdk with React Query across 11 feature domains (swap, money market, staking, bridge, dex, migration, partner, recovery, bitcoin/Bound Exchange, backend queries, shared). React-only — Node and backend code uses `@sodax/sdk` directly. Use whenever a React dapp needs SODAX feature hooks. Triggers on "use @sodax/dapp-kit", "useSwap", "useMoneyMarket", "useStake", "useBridge", "useDex", "useMigrate", any `use<Feature>` hook name from dapp-kit, "Sodax React hooks", "dapp-kit query / mutation". v2 hook shape: mutation hooks return `SafeUseMutationResult` with `mutateAsyncSafe(vars): Promise<Result<TData>>`. mutationFn unwraps SDK Result<T> and throws on `!ok` so React Query''s native error model engages. Hook-owned invalidations — consumer onSuccess runs after. MIGRATION (port v1 → v2) — a deep canonicalization pass: single-object hook params, mandatory `mutateAsyncSafe`, hook-owned invalidations, throw-on-`Result.!ok` inside `mutationFn`, canonical queryKey/mutationKey conventions. Plus the SDK underneath was reshaped (chain-key-driven routing, `Result<T>` everywhere, `WalletProviderSlot<K, Raw>`). v1 dapp-kit code will not compile against v2. Triggers on "migrate @sodax/dapp-kit", "useSpokeProvider gone", "dapp-kit v1 → v2", "invalidateMmQueries broken", "dapp-kit hook signatures changed", v1 fingerprints (positional args, hook-init `spokeProvider`, `useSpokeProvider`, `invalidateMmQueries`, legacy `useMigrate`, `*_MAINNET_CHAIN_ID`). Load this skill if EITHER applies; the body gates by mode.'
 ---
 
 # When to use this skill
@@ -32,7 +32,7 @@ Pick this mode when the consumer is a React dapp using `@sodax/dapp-kit` hooks.
 1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
 2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install + wire providers + first feature.
 3. Read [`integration/knowledge/architecture.md`](./integration/knowledge/architecture.md) — hook shapes, queryKey conventions, `useSafeMutation`, `unwrapResult`, `Result<T>`.
-4. For each feature you use, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md` (Radfi, dapp-kit-unique), `auxiliary-services.md` (partner + recovery + backend + shared).
+4. For each feature you use, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `bitcoin.md` (Bound Exchange, dapp-kit-unique), `auxiliary-services.md` (partner + recovery + backend + shared).
 5. Recipes → [`integration/knowledge/recipes/`](./integration/knowledge/recipes/) — `setup.md`, `wallet-connectivity.md`, per-feature, `mutation-error-handling.md`, `observability.md`, `invalidations.md`.
 6. Lookups → [`integration/knowledge/reference/`](./integration/knowledge/reference/) — `hooks-index.md`, `querykey-conventions.md`, `public-api.md`, `glossary.md`.
 

package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: sodax-dapp-kit-auxiliary-services
+description: 'Granular skill for the @sodax/dapp-kit v2 auxiliary surfaces — partner fee claiming (useFeeClaimSwap, useApproveToken, useSetSwapPreference, useGetAutoSwapPreferences, useIsTokenApproved), recovery (useHubAssetBalances, useWithdrawHubAsset), read-only backend queries (useBackendIntentByTxHash, useBackendUserIntents, useBackendOrderbook, useBackendMoneyMarketPosition, useBackendSubmitSwapTx), and shared utilities (useSodaxContext, useHubProvider, useXBalances, useDeriveUserWalletAddress, useEstimateGas, useStellarTrustlineCheck, useRequestTrustline). Use when a React dapp task is partner fees, recovering stuck hub assets, backend data reads (intent tracking / orderbook / MM data, no wallet), or cross-cutting utilities (token balances, gas estimation, Stellar trustlines). Covers BOTH integration and migration. Links into the parent sodax-dapp-kit knowledge tree.'
+---
+
+# Auxiliary services (dapp-kit granular skill)
+
+Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: **partner** (queryKey `partner`), **recovery** (`recovery`), **backend queries** (`backend`, read-only — no wallet), and **shared utilities** (`shared`). React-only — backend/Node uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which surface?**
+   - **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
+   - **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
+   - **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), swap submission (`useBackendSubmitSwapTx` mutation + `useBackendSubmitSwapTxStatus`).
+   - **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useRequestTrustline`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/auxiliary-services.md`](../integration/knowledge/features/auxiliary-services.md) — full hook surface for all four surfaces, `useXBalances` shape, trustline pattern, default polling intervals.
+4. Worked examples:
+   - Backend reads → [`../integration/knowledge/recipes/backend-queries.md`](../integration/knowledge/recipes/backend-queries.md).
+   - `useXBalances` → [`../integration/knowledge/recipes/wallet-connectivity.md`](../integration/knowledge/recipes/wallet-connectivity.md).
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Auxiliary-specific anti-patterns (dapp-kit)
+
+- **Treating `useFeeClaimSwap` `data` as a `SwapResponse`.** It's `IntentAutoSwapResult`.
+- **Passing top-level `pagination` to `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers`.** It nests under `params`; without it those queries are disabled.
+- **Calling `useXBalances` without `xService`.** Supply `xService` from `@sodax/wallet-sdk-react`'s `useXService`; the request-side key is `xChainId` (the cross-chain abstraction), distinct from the token-side `chainKey`.
+- **Treating `useRequestTrustline` as a canonical mutation hook.** It takes a single positional `token` arg and returns `{ requestTrustline, isLoading, ... }`; the callback takes `{ token, amount, srcChainKey, walletProvider }` (NOT `account`/`asset`).
+- **Running recovery on successful flows.** Recovery is a workaround for *failed* ops — `useHubAssetBalances` first, then withdraw the specific entry; investigate the original failure.
+- **Leaving `useBackendIntentByTxHash` polling (1s) running after the intent resolves.**
+
+## Migration workflow (port v1 auxiliary hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/auxiliary-services.md`](../migration-v1-to-v2/knowledge/features/auxiliary-services.md) — small per-hook changes across partner / recovery / backend / shared.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. `useBackendOrderbook` / paginated MM reads nest `pagination` under `params`.
+3. `useXBalances` is supplied an `xService`.
+4. Mutation flows (partner / recovery / submit) use `mutateAsyncSafe` and branch on `result.ok`.
+5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `useBackendSubmitSwapTx` + intent tracking are the backend half of the step-by-step swap flow; partner fee-claim reuses the swap intent layer.
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — backend MM reads complement the on-chain MM action hooks.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+Partner/recovery mutations take a `walletProvider`; `useXBalances` needs an `xService`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** for `useWalletProvider` and `useXService`. (Backend read hooks need no wallet.)

package/skills/sodax-dapp-kit/bitcoin/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: sodax-dapp-kit-bitcoin
+description: 'Granular skill for the @sodax/dapp-kit v2 Bitcoin/Radfi feature only — React Query hooks for Bitcoin trading via the Radfi protocol: useRadfiAuth, useRadfiSession, useTradingWallet, useFundTradingWallet, useRadfiWithdraw, useExpiredUtxos, useRenewUtxos, useBitcoinBalance, useTradingWalletBalance. This is a dapp-kit-UNIQUE surface (no @sodax/sdk equivalent — the flows are React-shaped). Use when a React dapp task is Bitcoin/Radfi (e.g. "Radfi session hook", "fund trading wallet hook", "Radfi withdraw in React", "manage Bitcoin UTXOs hook", "BIP322 auth with dapp-kit"). Covers BOTH integration (new v2 hooks) and migration (port v1 Radfi hooks — mostly signature tightening, flow unchanged). Links into the parent sodax-dapp-kit knowledge tree.'
+---
+
+# Bitcoin / Radfi (dapp-kit granular skill)
+
+Granular skill for the Bitcoin trading hooks of `@sodax/dapp-kit` v2 — authenticate (BIP322), fund a trading wallet, withdraw, manage UTXOs via the Radfi protocol. queryKey/mutationKey first segment: `bitcoin`. **Dapp-kit-unique** — no `@sodax/sdk` equivalent.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which stage?** Session/auth (`useRadfiAuth`, `useRadfiSession`, `useTradingWallet`), balances (`useBitcoinBalance`, `useTradingWalletBalance`), operations (`useFundTradingWallet`, `useRadfiWithdraw`), UTXO maintenance (`useExpiredUtxos`, `useRenewUtxos`).
+3. **Session lifecycle handled?** `useRadfiSession(walletProvider)` manages login/refresh/auto-refresh + localStorage persistence; gate trading buttons on `isAuthed`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/bitcoin.md`](../integration/knowledge/features/bitcoin.md) — full hook surface, session flow, mutation TVars, return shapes, polling notes.
+4. [`../integration/knowledge/recipes/bitcoin.md`](../integration/knowledge/recipes/bitcoin.md) — full worked examples (session, fund, withdraw, UTXO management).
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Bitcoin/Radfi-specific anti-patterns (dapp-kit)
+
+- **Calling trading operations before auth.** Gate on `useRadfiSession(...).isAuthed`; the trading wallet is created during first authentication, not as a separate step.
+- **Expecting `useTradingWallet` to fetch.** It's synchronous — reads the persisted session from localStorage (keyed by wallet address). Use it when you don't yet have a `walletProvider`.
+- **Hand-rolling PSBT signing for withdrawals.** `useRadfiWithdraw` orchestrates the unsigned-PSBT → local-sign → co-sign → broadcast flow; consumers don't touch PSBTs directly.
+- **Treating `useRadfiAuth` `data` as a full `RadfiSession`.** It's `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (no `publicKey` in the return; it's persisted internally).
+- **Leaving `useExpiredUtxos` polling (60s) on hidden UI.** Set `queryOptions.refetchInterval: false` when not visible.
+
+## Migration workflow (port v1 Radfi hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md).
+3. [`../migration-v1-to-v2/knowledge/features/bitcoin.md`](../migration-v1-to-v2/knowledge/features/bitcoin.md) — Radfi flow is mostly unchanged; provider/session lifecycle hook signatures tightened.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Trading buttons gate on `isAuthed`.
+3. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+4. No hand-rolled PSBT signing; `useRadfiWithdraw` owns the flow.
+
+## Related granular skills (same family)
+
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useXBalances` and other shared utilities used alongside Bitcoin UI.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+These hooks take an `IBitcoinWalletProvider`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire a Bitcoin wallet and obtain the provider via `useWalletProvider({ xChainId: ChainKeys.BITCOIN_MAINNET })`.

package/skills/sodax-dapp-kit/bridge/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: sodax-dapp-kit-bridge
+description: 'Granular skill for the @sodax/dapp-kit v2 bridge feature only — React Query hooks for cross-chain token transfer via the hub-and-spoke vault: useBridge, useBridgeApprove, useBridgeAllowance, useGetBridgeableAmount, useGetBridgeableTokens. Use when a React dapp task is specifically bridging (e.g. "useBridge with dapp-kit", "bridge tokens cross-chain in React", "check bridgeable amount hook", "list bridgeable destinations"). useBridge resolves to TxHashPair = { srcChainTxHash, dstChainTxHash }. Covers BOTH integration (new v2 hooks) and migration (port v1 bridge hooks — field renames srcChainId→srcChainKey, recipient→dstAddress, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# Bridge (dapp-kit granular skill)
+
+Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `bridge`. React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Need a bridgeable precheck?** `useGetBridgeableAmount` (vault deposit/withdrawal cap, returns a `BridgeLimit`) and `useGetBridgeableTokens` (enumerate compatible destinations).
+3. **Allowance gating?** `useBridgeAllowance` + `useBridgeApprove` before `useBridge`.
+4. **Source/destination chains + recipient format** — confirm both are supported spokes and the `recipient` matches the destination chain encoding.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — full hook surface, `CreateBridgeIntentParams` shape, `useBridgeAllowance` nesting, `BridgeLimit` return.
+4. [`../integration/knowledge/recipes/bridge.md`](../integration/knowledge/recipes/bridge.md) — full worked example.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### Bridge-specific anti-patterns (dapp-kit)
+
+- **Destructuring `useBridge` `data` as an array or single hash.** It resolves to `TxHashPair = { srcChainTxHash, dstChainTxHash }` — destructure by name.
+- **Treating `useGetBridgeableAmount` `data` as a bare bigint.** It's a `BridgeLimit = { amount, decimals, type }` — read `data.amount` / `data.decimals`.
+- **Passing addresses + chain ids to `useGetBridgeableAmount`.** It takes two `XToken` objects (each carries its own `chainKey`); v1's 4-arg shape is gone.
+- **Passing the bridge params directly under `params` on `useBridgeAllowance`.** They nest under `params.payload` alongside `walletProvider`.
+- **Submitting an incompatible token pair.** Tokens bridge only if they share the same hub vault — gate with `useGetBridgeableTokens` (incompatible pairs reject with `VALIDATION_FAILED`).
+
+## Migration workflow (port v1 bridge hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `recipient` → `dstAddress`); `useGetBridgeableAmount` shape change (bigint → `BridgeLimit`).
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. `useBridge` consumers destructure `{ srcChainTxHash, dstChainTxHash }` (no array/string).
+3. `useGetBridgeableAmount` consumers read `data.amount` (not a scalar).
+4. No `useSpokeProvider`, no `srcChainId`/`recipient` v1 field names (migration only).
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — intent-based cross-chain swaps (solver-routed; different from a direct vault bridge).
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for assets stranded on the hub after a failed bridge.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

package/skills/sodax-dapp-kit/dex/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: sodax-dapp-kit-dex
+description: 'Granular skill for the @sodax/dapp-kit v2 DEX feature only — React Query hooks for concentrated-liquidity LP plus asset deposit/withdraw: useDexDeposit, useDexWithdraw, useSupplyLiquidity, useDecreaseLiquidity, useClaimRewards, useDexApprove/useDexAllowance, the useCreate*Params builders, and reads (usePools, usePoolData, usePositionInfo, useLiquidityAmounts). Use when a React dapp task is concentrated-liquidity LP (e.g. "create LP position with dapp-kit", "useSupplyLiquidity hook", "increase/decrease liquidity in React", "claim LP fees hook", "deposit hub assets for LP"). Two-step flow: deposit assets → supply liquidity. Covers BOTH integration (new v2 hooks) and migration (port v1 dex hooks — field renames + srcChainKey, mint/increase routing). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
+---
+
+# DEX (dapp-kit granular skill)
+
+Granular skill for the concentrated-liquidity DEX hooks of `@sodax/dapp-kit` v2. queryKey/mutationKey first segment: `dex`. Two-step flow: `useDexDeposit` (spoke asset → hub ERC-4626 pool shares) then `useSupplyLiquidity` (shares → position). React-only — backend uses `@sodax/sdk` directly.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?** Asset deposit/withdraw (`useDexDeposit`/`useDexWithdraw`), supply liquidity (`useSupplyLiquidity` — mint-new OR increase-existing), decrease (`useDecreaseLiquidity`), claim fees (`useClaimRewards`).
+3. **Does opening a position require a deposit first?** Yes — positions hold hub pool shares; deposit from a spoke before supplying liquidity. UI flows usually combine the two steps.
+4. **Using the param builders?** `useCreate*Params` compute derived params (tick range, ERC-4626 conversions) client-side; spread their result into `mutate({ params: { ...result, srcChainKey, srcAddress }, walletProvider })`.
+
+## Integration workflow (new v2 code)
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. [`../integration/knowledge/architecture.md`](../integration/knowledge/architecture.md) — hook shapes, `mutateAsyncSafe`, `unwrapResult`, queryKey conventions.
+3. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — full hook surface, SDK param types, the FLAT-props param builders, position-lifecycle notes.
+4. [`../integration/knowledge/recipes/dex.md`](../integration/knowledge/recipes/dex.md) — full worked examples.
+5. Call-shape choice → [`../integration/knowledge/recipes/mutation-error-handling.md`](../integration/knowledge/recipes/mutation-error-handling.md).
+
+### DEX-specific anti-patterns (dapp-kit)
+
+- **Skipping `useDexDeposit` before `useSupplyLiquidity`.** Positions reference hub pool shares; without a deposit there's nothing to provide.
+- **Wrapping param builders in `{ params }`.** `useCreate*Params` take a FLAT props object (not `{ params }`-wrapped) and return memoized derived params; you add `srcChainKey` + `srcAddress` at the mutation call site.
+- **Treating ticks as prices.** `tickLower`/`tickUpper` are logarithmic indices — convert with Q96 math / SDK helpers.
+- **Calling a separate hook for increase-existing.** `useSupplyLiquidity` fans out to mint-new vs increase based on `params.tokenId` + `isValidPosition`; `useCreateSupplyLiquidityParams` handles the routing.
+- **`usePositionInfo` `tokenId` is `string | null`, not bigint.**
+- **Expecting `usePools` to auto-refresh.** It's `staleTime: Infinity` (static config).
+
+## Migration workflow (port v1 dex hooks to v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
+2. Cross-cutting deltas: [`../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md`](../migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md), [`../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md`](../migration-v1-to-v2/knowledge/breaking-changes/result-handling.md), [`../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md`](../migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md).
+3. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — two-step flow unchanged; field renames + `srcChainKey` requirement; `useSupplyLiquidity` mint/increase routing.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Deposit precedes supply in combined flows.
+3. Param-builder output is spread with `srcChainKey`/`srcAddress` added at the call site.
+4. Mutation flows use `mutateAsyncSafe` and branch on `result.ok`.
+5. No `useSpokeProvider`, no hook-level `spokeProvider` (migration only).
+
+## Related granular skills (same family)
+
+- [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — recovery (`useWithdrawHubAsset`) for stuck hub LP assets; `useXBalances` / gas utilities.
+
+For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
+
+## Wallet connectivity (different SDK package family)
+
+`walletProvider` flows through `mutate(vars)`. **Also load the `sodax-wallet-sdk-react` skill (integration mode)** to wire wallets and get a typed `walletProvider` via `useWalletProvider({ xChainId: chainKey })`.

package/skills/sodax-dapp-kit/integration/knowledge/README.md

@@ -15,7 +15,7 @@ This tree documents v2 of the dapp-kit React hooks for **new consumers** buildin
 | [`features/bridge.md`](features/bridge.md) | Bridge hooks: `useBridge`, allowance/approve, bridgeable amount/tokens. |
 | [`features/dex.md`](features/dex.md) | DEX hooks: deposit/withdraw, supply/decrease liquidity, claim rewards, position info, pools. |
 | [`features/migration.md`](features/migration.md) | Migration hooks: ICX/bnUSD/BALN forward + reverse, allowance/approve. |
-| [`features/bitcoin.md`](features/bitcoin.md) | Radfi hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`features/bitcoin.md`](features/bitcoin.md) | Bound Exchange hooks (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
 | [`features/auxiliary-services.md`](features/auxiliary-services.md) | Partner, recovery, backend queries, shared (xBalances, gas estimation, trustlines). |
 | [`recipes/`](recipes/) | Copy-paste patterns: setup, wallet connectivity, per-feature flows, mutation error handling, observability, invalidations. |
 | [`reference/`](reference/) | Lookup tables: full hook index, queryKey conventions, public API surface, glossary. |

package/skills/sodax-dapp-kit/integration/knowledge/features/README.md

@@ -10,7 +10,7 @@ Per-feature reference docs. Each file documents the hooks, params types, return
 | [`bridge.md`](bridge.md) | Cross-chain token bridging: `useBridge`, allowance/approve, bridgeable amount/tokens. |
 | [`dex.md`](dex.md) | Concentrated liquidity DEX: assets in/out, liquidity supply/decrease, claim rewards, position info, pool reads, param builders. |
 | [`migration.md`](migration.md) | Token migration: `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln`, allowance/approve. |
-| [`bitcoin.md`](bitcoin.md) | Radfi (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
+| [`bitcoin.md`](bitcoin.md) | Bound Exchange (dapp-kit-unique): session, trading wallet, fund/withdraw, UTXOs. |
 | [`auxiliary-services.md`](auxiliary-services.md) | Partner fee claiming, recovery, backend queries (intent tracking, orderbook, MM data), shared utilities (xBalances, gas, trustlines). |
 
 ## Reference vs recipes

package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md

@@ -94,6 +94,10 @@ useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet r
 useEstimateGas({ mutationOptions });                // Gas estimation for raw tx
 useStellarTrustlineCheck({ params, queryOptions });
 useRequestTrustline({ mutationOptions });
+useNearStorageCheck({ params, queryOptions });      // NEP-141 storage registration check (NEAR)
+useRegisterNearStorage({ mutationOptions });        // NEP-141 storage_deposit (NEAR)
+useNearStorageGate({ dstChainKey, token, accountId, walletProvider }); // composite NEAR receive-side gate
+resolveNearStorageGate(chainKey, check);            // unwrapped util: gate-state from a useNearStorageCheck result
 ```
 
 ### `useXBalances` shape
@@ -144,6 +148,46 @@ if (hasTrustline === false) {
 }
 ```
 
+### NEAR storage registration
+
+NEP-141 accounts must pay a one-time storage bond before they can receive a token — delivering to an unregistered account fails. The receive-side analogue of Stellar trustlines: gate any flow that delivers a token to the user on NEAR (swap output on NEAR, bridge into NEAR, money-market borrow/withdraw to NEAR). Use `useNearStorageGate` for app UI; use the lower-level `useNearStorageCheck` + `useRegisterNearStorage` pair when you need custom wiring.
+
+```ts
+// @ai-snippets-skip — illustrative only; real types pulled into agents below.
+// useNearStorageCheck is a canonical read hook: { params: { token, accountId, chainId }, queryOptions }.
+// `chainId` is a SpokeChainKey typed loosely — the hook returns `true` for non-NEAR chains (safe to
+// gate conditionally) and `true` for native NEAR (not a NEP-141 token). data is a boolean;
+// queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId].
+const { data: isRegistered, isLoading } = useNearStorageCheck({
+  params: { token, accountId, chainId: ChainKeys.NEAR_MAINNET },
+});
+
+// useRegisterNearStorage IS a canonical mutation hook: { mutationOptions }, returns
+// SafeUseMutationResult. Domain inputs flow through mutate / mutateAsync / mutateAsyncSafe.
+// Vars: { token, accountId, walletProvider, deposit? } — deposit defaults to the NEP-141
+// storage bond (0.00125 NEAR). mutationKey: ['shared', 'registerNearStorage'].
+const { mutateAsyncSafe: registerStorage } = useRegisterNearStorage();
+if (isRegistered === false) {
+  await registerStorage({ token, accountId, walletProvider });
+}
+```
+
+For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, isRegistering, registerStorage }`.
+
+Derive UI gate flags with the unwrapped `resolveNearStorageGate` util (no hook) when you need custom check/register composition:
+
+```ts
+// @ai-snippets-skip — illustrative only.
+// resolveNearStorageGate(chainKey, check) reads `isLoading` + `data` off the useNearStorageCheck
+// result and returns { isNear, needsRegistration, blocksAction }:
+//   needsRegistration — show the register action (check resolved AND not registered)
+//   blocksAction      — keep the downstream action disabled (still checking OR needs registration)
+const check = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
+const { needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, check);
+```
+
+The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEAR spoke service, and the `NEAR_STORAGE_DEPOSIT` constant) are documented in the `sodax-sdk` skill (integration mode).
+
 ## Default polling intervals
 
 | Hook | Polling | Notes |

package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md

@@ -1,6 +1,6 @@
-# Bitcoin (Radfi) — `@sodax/dapp-kit`
+# Bitcoin (Bound Exchange) — `@sodax/dapp-kit`
 
-Bitcoin trading via the Radfi protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
+Bitcoin trading via the Bound Exchange protocol — authenticate, fund a trading wallet, withdraw, manage UTXOs. **Dapp-kit-unique surface** (no SDK equivalent — these flows are React-shaped).
 
 Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md).
 
@@ -15,7 +15,7 @@ useTradingWallet(walletAddress);                 // Synchronous: read persisted
 
 // Balances
 useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions });             // Personal wallet (default mempool.space)
-useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Radfi API
+useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Bound Exchange API
 
 // Operations
 useFundTradingWallet({ mutationOptions });
@@ -26,7 +26,7 @@ useRenewUtxos({ mutationOptions });
 
 ## Session flow
 
-Radfi requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
+Bound Exchange requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
 
 ```ts
 // @ai-snippets-skip
@@ -76,8 +76,8 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
 
 1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
 2. **Trading wallet is created during first authentication** — not a separate step.
-3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Radfi session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
-4. **PSBT signing flow for withdrawals.** Radfi server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
+3. **`useTradingWallet(walletAddress)` is synchronous** (no network call). It reads persisted Bound Exchange session from localStorage. Use it when you don't have a `walletProvider` available yet but need the trading address.
+4. **PSBT signing flow for withdrawals.** Bound Exchange server builds an unsigned PSBT, the user signs locally via the wallet provider, then submits back for co-signing and broadcast. The dapp-kit hook orchestrates this — consumers don't see PSBTs directly.
 5. **Session tokens are for API rate-limiting, not asset access.** Stored in localStorage keyed by wallet address. Compromise of localStorage data doesn't affect funds.
 6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
 

package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md

@@ -43,6 +43,8 @@ type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
   userAddress: string | undefined;
 }>;
 // Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
+// Bitcoin: always pass the personal address as userAddress — the hook transparently resolves to the
+// Bound Exchange trading-wallet-derived hub wallet when a session is active (local lookup, no network).
 
 // useAToken — single aToken metadata; FLAT (no chain/user fields)
 type UseATokenParams = ReadHookParams<ATokenData, {
@@ -57,10 +59,13 @@ type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
   userAddress: string | undefined;
 }>;
 // Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
+// Bitcoin: always pass the personal address — trading-wallet resolution is automatic when a session exists.
 ```
 
 > **Read-side chain key is `spokeChainKey`, not `srcChainKey`.** Mutation hooks (`useSupply`/`useBorrow`/etc.) use `srcChainKey` because the request crosses chains and needs a source. Read hooks describe a user's position on a single spoke chain — the field is `spokeChainKey`. Applies to `useATokensBalances`, `useUserFormattedSummary`, and `useUserReservesData` (`useAToken` is metadata-only and takes neither). Don't grep-replace one for the other.
 
+> **Bitcoin `userAddress`**: always pass the **personal** address (the user's wallet address), not the Bound Exchange trading address. The read hooks (`useATokensBalances`, `useUserReservesData`, `useUserFormattedSummary`, `useGetUserHubWalletAddress`) automatically resolve to the trading-wallet-derived hub wallet when a Bound Exchange session is active — this is a local lookup with no network call and no throw on an unauthenticated session. See [`features/bitcoin.md`](bitcoin.md) for Bound Exchange session setup.
+
 ## Mutation params
 
 All four user mutations share the same TVars shape (only the `action` literal differs):

package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md

@@ -1,6 +1,6 @@
-# Recipe: Bitcoin (Radfi)
+# Recipe: Bitcoin (Bound Exchange)
 
-Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
+Bitcoin trading via the Bound Exchange protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
 
 **Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
 
@@ -10,7 +10,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 
 | Hook | Type | Purpose |
 |------|------|---------|
-| `useRadfiAuth` | Mutation | Authenticate with Radfi via BIP322 signing |
+| `useRadfiAuth` | Mutation | Authenticate with Bound Exchange via BIP322 signing |
 | `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
 | `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
 
@@ -19,7 +19,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 | 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) |
+| `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API (confirmed + pending) |
 
 ### Operations
 
@@ -32,7 +32,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
 
 ## Session Flow
 
-Radfi requires authentication before any trading operation. The typical flow:
+Bound Exchange requires authentication before any trading operation. The typical flow:
 
 ```tsx
 import { useRadfiSession } from '@sodax/dapp-kit';
@@ -49,7 +49,7 @@ function BitcoinAuth() {
 
   return (
     <button onClick={login} disabled={isLoginPending}>
-      {isLoginPending ? 'Signing...' : 'Login to Radfi'}
+      {isLoginPending ? 'Signing...' : 'Login to Bound Exchange'}
     </button>
   );
 }
@@ -77,7 +77,7 @@ function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
     params: { address: walletAddress },
   });
 
-  // Trading wallet balance (from Radfi API). `RadfiWalletBalance` fields:
+  // Trading wallet balance (from Bound Exchange API). `RadfiWalletBalance` fields:
   // `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
   const { data: tradingBalance } = useTradingWalletBalance({
     params: { walletProvider, tradingAddress },
@@ -188,6 +188,6 @@ function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
 
 - **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.
+- **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Bound Exchange 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/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md

@@ -16,6 +16,9 @@ Connect wallets and pass wallet providers to feature hooks.
 | `useEstimateGas` | `@sodax/dapp-kit` | Mutation | Estimate gas for raw transactions |
 | `useStellarTrustlineCheck` | `@sodax/dapp-kit` | Query | Check if Stellar account has sufficient trustline |
 | `useRequestTrustline` | `@sodax/dapp-kit` | Mutation | Request a Stellar trustline for a token |
+| `useNearStorageCheck` | `@sodax/dapp-kit` | Query | Check if a NEAR account is NEP-141 storage-registered for a token |
+| `useRegisterNearStorage` | `@sodax/dapp-kit` | Mutation | Submit a NEP-141 `storage_deposit` so a NEAR account can receive a token |
+| `useNearStorageGate` | `@sodax/dapp-kit` | Hook | Combine the NEAR storage check, registration mutation, and UI gate flags |
 
 ## Connect a Wallet
 

package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md

@@ -130,7 +130,7 @@ App-level React component. Provides:
 - RPC config for all chains
 - Hub provider access (via `useHubProvider()`)
 
-Optional config: `<SodaxProvider config={DeepPartial<SodaxConfig>}>`. Without config, SDK uses packaged defaults.
+Optional config: `<SodaxProvider config={SodaxOptions}>` (`SodaxOptions = DeepPartial<SodaxConfig> & { logger? }`). Without config, SDK uses packaged defaults.
 
 Config is tracked by **reference** - see [`recipes/setup.md § Config reactivity`](../recipes/setup.md#config-reactivity) for module-const vs `useMemo` patterns.