@sodax/skills 2.0.0-rc.8 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (168) hide show
  1. package/.claude-plugin/plugin.json +1 -0
  2. package/AGENTS.md +123 -13
  3. package/README.md +5 -2
  4. package/package.json +1 -1
  5. package/skills/sodax-build/SKILL.md +90 -0
  6. package/skills/sodax-build/knowledge/README.md +35 -0
  7. package/skills/sodax-build/knowledge/brief-template.md +41 -0
  8. package/skills/sodax-build/knowledge/chains-and-assets.md +26 -0
  9. package/skills/sodax-build/knowledge/example-sessions.md +84 -0
  10. package/skills/sodax-build/knowledge/feature-catalog.md +51 -0
  11. package/skills/sodax-build/knowledge/glossary.md +35 -0
  12. package/skills/sodax-build/knowledge/handoff.md +60 -0
  13. package/skills/sodax-build/knowledge/interview-guide.md +66 -0
  14. package/skills/sodax-build/knowledge/monetization.md +37 -0
  15. package/skills/sodax-build/knowledge/use-case-gallery.md +32 -0
  16. package/skills/sodax-dapp-kit/SKILL.md +6 -2
  17. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +65 -0
  18. package/skills/sodax-dapp-kit/bitcoin/SKILL.md +57 -0
  19. package/skills/sodax-dapp-kit/bridge/SKILL.md +59 -0
  20. package/skills/sodax-dapp-kit/dex/SKILL.md +60 -0
  21. package/skills/sodax-dapp-kit/integration/knowledge/README.md +1 -1
  22. package/skills/sodax-dapp-kit/integration/knowledge/features/README.md +3 -2
  23. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +71 -11
  24. package/skills/sodax-dapp-kit/integration/knowledge/features/bitcoin.md +10 -6
  25. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  26. package/skills/sodax-dapp-kit/integration/knowledge/features/leverage-yield.md +112 -0
  27. package/skills/sodax-dapp-kit/integration/knowledge/features/migration.md +1 -1
  28. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +6 -1
  29. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  30. package/skills/sodax-dapp-kit/integration/knowledge/quickstart.md +2 -2
  31. package/skills/sodax-dapp-kit/integration/knowledge/recipes/README.md +1 -0
  32. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  33. package/skills/sodax-dapp-kit/integration/knowledge/recipes/bitcoin.md +8 -8
  34. package/skills/sodax-dapp-kit/integration/knowledge/recipes/leverage-yield.md +168 -0
  35. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  36. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +4 -4
  37. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  38. package/skills/sodax-dapp-kit/integration/knowledge/recipes/wallet-connectivity.md +3 -0
  39. package/skills/sodax-dapp-kit/integration/knowledge/reference/glossary.md +1 -1
  40. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +67 -6
  41. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +49 -0
  42. package/skills/sodax-dapp-kit/leverage-yield/SKILL.md +54 -0
  43. package/skills/sodax-dapp-kit/migration/SKILL.md +64 -0
  44. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/hook-signatures.md +1 -1
  45. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +2 -2
  46. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/checklist.md +1 -1
  47. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/README.md +1 -1
  48. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +19 -10
  49. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bitcoin.md +2 -2
  50. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  51. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  52. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md +1 -1
  53. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +3 -3
  54. package/skills/sodax-dapp-kit/money-market/SKILL.md +61 -0
  55. package/skills/sodax-dapp-kit/staking/SKILL.md +60 -0
  56. package/skills/sodax-dapp-kit/swap/SKILL.md +64 -0
  57. package/skills/sodax-sdk/SKILL.md +54 -50
  58. package/skills/sodax-sdk/backend-api/SKILL.md +58 -0
  59. package/skills/sodax-sdk/bridge/SKILL.md +53 -0
  60. package/skills/sodax-sdk/dex/SKILL.md +54 -0
  61. package/skills/sodax-sdk/integration/knowledge/README.md +5 -3
  62. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  63. package/skills/sodax-sdk/integration/knowledge/architecture.md +26 -39
  64. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +57 -10
  65. package/skills/sodax-sdk/integration/knowledge/features/README.md +6 -3
  66. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +92 -0
  67. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +48 -11
  68. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  69. package/skills/sodax-sdk/integration/knowledge/features/leverage-yield.md +175 -0
  70. package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md} +75 -30
  71. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +20 -25
  72. package/skills/sodax-sdk/integration/knowledge/features/partner.md +86 -0
  73. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +51 -0
  74. package/skills/sodax-sdk/integration/knowledge/features/staking.md +8 -3
  75. package/skills/sodax-sdk/integration/knowledge/features/swap.md +106 -22
  76. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  77. package/skills/sodax-sdk/integration/knowledge/quickstart.md +1 -1
  78. package/skills/sodax-sdk/integration/knowledge/recipes/README.md +1 -0
  79. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  80. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  81. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +34 -2
  82. package/skills/sodax-sdk/integration/knowledge/recipes/logging.md +102 -0
  83. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +28 -4
  84. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  85. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  86. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  87. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +40 -4
  88. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +32 -9
  89. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  90. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +37 -4
  91. package/skills/sodax-sdk/leverage-yield/SKILL.md +50 -0
  92. package/skills/sodax-sdk/migration/SKILL.md +69 -0
  93. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  94. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +6 -10
  95. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  96. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  97. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  98. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +2 -2
  99. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/README.md +4 -2
  100. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +92 -0
  101. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  102. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  103. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/{icx-bnusd-baln.md → migration.md} +31 -29
  104. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  105. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +64 -0
  106. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +35 -0
  107. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +8 -3
  108. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  109. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +19 -17
  110. package/skills/sodax-sdk/money-market/SKILL.md +56 -0
  111. package/skills/sodax-sdk/partner/SKILL.md +55 -0
  112. package/skills/sodax-sdk/recovery/SKILL.md +53 -0
  113. package/skills/sodax-sdk/staking/SKILL.md +53 -0
  114. package/skills/sodax-sdk/swap/SKILL.md +72 -0
  115. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  116. package/skills/sodax-wallet-sdk-core/SKILL.md +7 -3
  117. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +54 -0
  118. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +54 -0
  119. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +54 -0
  120. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +54 -0
  121. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  122. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +2 -2
  123. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  124. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  125. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  126. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  127. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  128. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  129. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  130. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  131. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  132. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  133. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  134. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  135. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  136. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/testing.md +1 -1
  137. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  138. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  139. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  140. package/skills/sodax-wallet-sdk-core/migration-v1-to-v2/knowledge/README.md +1 -1
  141. package/skills/sodax-wallet-sdk-core/near/SKILL.md +54 -0
  142. package/skills/sodax-wallet-sdk-core/solana/SKILL.md +54 -0
  143. package/skills/sodax-wallet-sdk-core/stacks/SKILL.md +53 -0
  144. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +54 -0
  145. package/skills/sodax-wallet-sdk-core/sui/SKILL.md +53 -0
  146. package/skills/sodax-wallet-sdk-react/SKILL.md +5 -3
  147. package/skills/sodax-wallet-sdk-react/bridge-to-sdk/SKILL.md +56 -0
  148. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +59 -0
  149. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  150. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  151. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  152. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  153. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  154. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +4 -4
  155. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  156. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  157. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  158. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  159. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  160. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  161. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/ssr-setup.md +24 -19
  162. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/reference/config.md +1 -1
  163. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +51 -0
  164. package/skills/sodax-wallet-sdk-react/switch-chain/SKILL.md +51 -0
  165. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +54 -0
  166. package/skills/sodax-wallet-sdk-react/walletconnect/SKILL.md +52 -0
  167. package/skills/sodax-sdk/integration/knowledge/features/auxiliary-services.md +0 -189
  168. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/auxiliary-services.md +0 -156
@@ -64,22 +64,36 @@ useBackendMoneyMarketAssetBorrowers({ params, queryOptions });
64
64
  useBackendAllMoneyMarketBorrowers({ params: { pagination: { offset, limit } }, queryOptions });
65
65
  ```
66
66
 
67
- ### Swap submission
67
+ ### Swaps API (`sodax.api.swaps`)
68
+
69
+ Typed React Query wrappers over the backend **Swaps API v2** — one `useSwapsApi*` hook per endpoint of `sodax.api.swaps.*` (21 total: tokens, quote, deadline, allowance, approve, create / submit / cancel intent, status, intent hash / packet / extra-data, intent lookups, limit orders, gas estimate, fees, submit-tx + status). They call the backend HTTP API and are distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive `sodax.swaps` (the on-chain `SwapService`). Reads take `{ params, queryOptions }`; the six actions (`approve`, `createIntent`, `submitIntent`, `cancelIntent`, `createLimitOrder`, `submitTx`) are mutations taking `{ mutationOptions }`, with domain inputs flowing through `mutate(vars)`.
70
+
71
+ ```ts
72
+ // @ai-snippets-skip
73
+ useSwapsApiQuote({ params: { body }, queryOptions }); // query → sodax.api.swaps.getQuote
74
+ useSwapsApiSubmitTx({ mutationOptions }); // mutation → sodax.api.swaps.submitTx
75
+ useSwapsApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.swaps.getSubmitTxStatus
76
+ ```
77
+
78
+ `useSwapsApiSubmitTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`. The `request` is a `SubmitTxRequestV2` (`{ txHash, srcChainKey, walletAddress, intent, relayData }`):
68
79
 
69
80
  ```ts
70
81
  // @ai-snippets-skip
71
- useBackendSubmitSwapTx({ mutationOptions }); // Mutation
72
- useBackendSubmitSwapTxStatus({ params, queryOptions }); // Query — check submitted status
82
+ const { mutateAsync: submitSwapTx } = useSwapsApiSubmitTx();
83
+ // request: SubmitTxRequestV2 — relayData is the string payload; intent carries bigint fields
84
+ await submitSwapTx({ request, apiConfig: { baseURL: 'https://...' } });
73
85
  ```
74
86
 
75
- `useBackendSubmitSwapTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`:
87
+ `useSwapsApiSubmitTxStatus` polls the processing status and returns `SubmitTxStatusResponseV2 | undefined`. Its query runs only when **both** `txHash` and `srcChainKey` are supplied — the v2 status endpoint requires the source chain key:
76
88
 
77
89
  ```ts
78
90
  // @ai-snippets-skip
79
- const { mutateAsync: submitSwapTx } = useBackendSubmitSwapTx();
80
- await submitSwapTx({ request: swapPayload, apiConfig: { baseURL: 'https://...' } });
91
+ const { data: status } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
92
+ // status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | 'posted_execution' | 'solved' | 'failed'
81
93
  ```
82
94
 
95
+ > The full `useSwapsApi*` hook list (with polling + types) is in [hooks-index.md](../reference/hooks-index.md); key shapes in [querykey-conventions.md](../reference/querykey-conventions.md). For non-React callers, `sodax.api.swaps` is documented in the `sodax-sdk` skill (integration mode).
96
+
83
97
  ## Shared utilities
84
98
 
85
99
  Cross-cutting hooks used by other features.
@@ -94,6 +108,10 @@ useGetUserHubWalletAddress({ params, queryOptions }); // Hub wallet via wallet r
94
108
  useEstimateGas({ mutationOptions }); // Gas estimation for raw tx
95
109
  useStellarTrustlineCheck({ params, queryOptions });
96
110
  useRequestTrustline({ mutationOptions });
111
+ useNearStorageCheck({ params, queryOptions }); // NEP-141 storage registration check (NEAR)
112
+ useRegisterNearStorage({ mutationOptions }); // NEP-141 storage_deposit (NEAR)
113
+ useNearStorageGate({ dstChainKey, token, accountId, walletProvider }); // composite NEAR receive-side gate
114
+ resolveNearStorageGate(chainKey, check); // unwrapped util: gate-state from a useNearStorageCheck result
97
115
  ```
98
116
 
99
117
  ### `useXBalances` shape
@@ -125,11 +143,12 @@ Stellar accounts that have never held an asset have no trustline — receiving w
125
143
 
126
144
  ```ts
127
145
  // @ai-snippets-skip — illustrative only; real types pulled into agents below.
128
- // useStellarTrustlineCheck takes { token, amount, chainId, walletProvider } under params.
129
- // `chainId` here is a `SpokeChainKey` (typed loosely so consumers can pass any chain key —
130
- // the hook returns `true` for non-Stellar chains, making it safe to gate on conditionally).
146
+ // useStellarTrustlineCheck reads a trustline (no signing). Pass the resolved Stellar account
147
+ // `walletAddress` (e.g. useXAccount('STELLAR').address) — it keys the cache per account, so the
148
+ // verdict is never reused across accounts. `chainId` is a `SpokeChainKey` (typed loosely — the hook
149
+ // returns `true` for non-Stellar chains, making it safe to gate on conditionally).
131
150
  const { data: hasTrustline } = useStellarTrustlineCheck({
132
- params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET, walletProvider },
151
+ params: { token, amount, chainId: ChainKeys.STELLAR_MAINNET, walletAddress },
133
152
  });
134
153
 
135
154
  // useRequestTrustline is NOT a canonical mutation hook — it takes a single positional
@@ -144,12 +163,53 @@ if (hasTrustline === false) {
144
163
  }
145
164
  ```
146
165
 
166
+ ### NEAR storage registration
167
+
168
+ 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.
169
+
170
+ ```ts
171
+ // @ai-snippets-skip — illustrative only; real types pulled into agents below.
172
+ // useNearStorageCheck is a canonical read hook: { params: { token, accountId, chainId }, queryOptions }.
173
+ // `chainId` is a SpokeChainKey typed loosely — the hook returns `true` for non-NEAR chains (safe to
174
+ // gate conditionally) and `true` for native NEAR (not a NEP-141 token). data is a boolean;
175
+ // queryKey: ['shared', 'nearStorageCheck', chainId, token, accountId].
176
+ const { data: isRegistered, isLoading } = useNearStorageCheck({
177
+ params: { token, accountId, chainId: ChainKeys.NEAR_MAINNET },
178
+ });
179
+
180
+ // useRegisterNearStorage IS a canonical mutation hook: { mutationOptions }, returns
181
+ // SafeUseMutationResult. Domain inputs flow through mutate / mutateAsync / mutateAsyncSafe.
182
+ // Vars: { token, accountId, walletProvider, deposit? } — deposit defaults to the NEP-141
183
+ // storage bond (0.00125 NEAR). mutationKey: ['shared', 'registerNearStorage'].
184
+ const { mutateAsyncSafe: registerStorage } = useRegisterNearStorage();
185
+ if (isRegistered === false) {
186
+ await registerStorage({ token, accountId, walletProvider });
187
+ }
188
+ ```
189
+
190
+ For the common UI path, `useNearStorageGate` returns `{ isNear, needsRegistration, blocksAction, isChecking, isRegistering, registerStorage }`.
191
+
192
+ Derive UI gate flags with the unwrapped `resolveNearStorageGate` util (no hook) when you need custom check/register composition:
193
+
194
+ ```ts
195
+ // @ai-snippets-skip — illustrative only.
196
+ // resolveNearStorageGate(chainKey, check) reads `isLoading` + `data` off the useNearStorageCheck
197
+ // result and returns { isNear, needsRegistration, blocksAction }:
198
+ // needsRegistration — show the register action (check resolved AND not registered)
199
+ // blocksAction — keep the downstream action disabled (still checking OR needs registration)
200
+ const check = useNearStorageCheck({ params: { token, accountId, chainId: dstChainKey } });
201
+ const { needsRegistration, blocksAction } = resolveNearStorageGate(dstChainKey, check);
202
+ ```
203
+
204
+ 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).
205
+
147
206
  ## Default polling intervals
148
207
 
149
208
  | Hook | Polling | Notes |
150
209
  |---|---|---|
151
210
  | `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
152
- | `useBackendSubmitSwapTxStatus` | varies | poll stops on `executed` / `failed` |
211
+ | `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `solved` / `failed` |
212
+ | `useSwapsApiStatus` | 1s | solver intent status; stops on status `3` / `4` |
153
213
  | `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
154
214
  | `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
155
215
  | `useQuote` (swap) | 3s | refetchInterval |
@@ -1,6 +1,6 @@
1
- # Bitcoin (Radfi) — `@sodax/dapp-kit`
1
+ # Bitcoin (Bound Exchange) — `@sodax/dapp-kit`
2
2
 
3
- 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).
3
+ 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).
4
4
 
5
5
  Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bitcoin.md).
6
6
 
@@ -11,11 +11,12 @@ Pair: [`features/bitcoin.md`](../../../migration-v1-to-v2/knowledge/features/bit
11
11
  // Session lifecycle
12
12
  useRadfiAuth({ mutationOptions }); // Authenticate via BIP322 signing
13
13
  useRadfiSession(walletProvider); // Manage full lifecycle (login, refresh, auto-refresh)
14
+ useEnsureRadfiAccessToken({ mutationOptions }); // Ensure a fresh Bound token; resolves to the token string
14
15
  useTradingWallet(walletAddress); // Synchronous: read persisted session
15
16
 
16
17
  // Balances
17
18
  useBitcoinBalance({ params: { address, rpcUrl? }, queryOptions }); // Personal wallet (default mempool.space)
18
- useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Radfi API
19
+ useTradingWalletBalance({ params: { walletProvider, tradingAddress }, queryOptions }); // Bound Exchange API
19
20
 
20
21
  // Operations
21
22
  useFundTradingWallet({ mutationOptions });
@@ -24,9 +25,11 @@ useExpiredUtxos({ params: { walletProvider, tradingAddress }, queryOptions }); /
24
25
  useRenewUtxos({ mutationOptions });
25
26
  ```
26
27
 
28
+ `useEnsureRadfiAccessToken` is for raw / server-side `createIntent`: it resolves a valid Bound token to forward as `extras.bound.accessToken` (the Bitcoin-gated `bound` slot) on a `raw: true` swap intent, or as `bound.accessToken` on a backend createIntent DTO. See the `sodax-sdk` skill (swap feature) for the `extras.bound` slot.
29
+
27
30
  ## Session flow
28
31
 
29
- Radfi requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
32
+ Bound Exchange requires authentication before trading operations. `useRadfiSession` handles the full lifecycle:
30
33
 
31
34
  ```ts
32
35
  // @ai-snippets-skip
@@ -63,6 +66,7 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
63
66
  | Hook | Returns |
64
67
  |---|---|
65
68
  | `useRadfiAuth` | `SafeUseMutationResult<RadfiAuthResult, Error, UseRadfiAuthVars>` where `RadfiAuthResult = { accessToken, refreshToken, tradingAddress }` (3 fields, NOT `RadfiSession` — the hook persists `publicKey` to localStorage internally but doesn't return it) |
69
+ | `useEnsureRadfiAccessToken` | `SafeUseMutationResult<string, Error, { walletProvider }>` — resolves to a valid Bound Exchange access token (silent refresh when possible, else BIP322 re-auth) |
66
70
  | `useFundTradingWallet` | `SafeUseMutationResult<TxId, Error, ...>` |
67
71
  | `useRadfiWithdraw` | `SafeUseMutationResult<{ txId, fee }, Error, ...>` |
68
72
  | `useRenewUtxos` | `SafeUseMutationResult<TxId, Error, ...>` |
@@ -76,8 +80,8 @@ type RenewUtxosVars = { txIdVouts: string[]; walletProvider: IBitcoinWalletProvi
76
80
 
77
81
  1. **Authentication required before any trading operation.** `useRadfiSession` manages this automatically — gate buttons on `isAuthed`.
78
82
  2. **Trading wallet is created during first authentication** — not a separate step.
79
- 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.
80
- 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.
83
+ 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.
84
+ 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.
81
85
  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.
82
86
  6. **`useExpiredUtxos` polls every 60s** — set `queryOptions.refetchInterval: false` to disable while UI is hidden.
83
87
 
@@ -29,8 +29,8 @@ useLiquidityAmounts({ params, queryOptions });
29
29
  // Param builders (compute derived params client-side) — these take a FLAT props object,
30
30
  // NOT a `{ params }` wrapper. They return memoized derived params that the consumer adds
31
31
  // `srcChainKey` + `srcAddress` to at the mutation call site.
32
- useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
33
- useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? });
32
+ useCreateDepositParams({ tokenIndex, amount, poolData, poolSpokeAssets }); // no dst — deposits always target the hub
33
+ useCreateWithdrawParams({ tokenIndex, amount, poolData, poolSpokeAssets, dst? }); // dst? — withdraw routes hub → spoke
34
34
  useCreateSupplyLiquidityParams({ poolData, poolKey, minPrice, maxPrice, liquidityToken0Amount, liquidityToken1Amount, slippageTolerance, positionId?, isValidPosition? });
35
35
  useCreateDecreaseLiquidityParams({ /* see source for fields */ });
36
36
  ```
@@ -0,0 +1,112 @@
1
+ # Leverage Yield — `@sodax/dapp-kit`
2
+
3
+ Leveraged-yield ERC-4626 vaults on the Sonic hub. Deposit any token → `lsoda*` vault shares, withdraw shares → any token; plus position / APR / TVL / share-balance reads. New in v2 (no v1 equivalent).
4
+
5
+ ## Hook surface
6
+
7
+ ```ts
8
+ // @ai-snippets-skip
9
+ // Mutations
10
+ useLeverageYieldDeposit({ mutationOptions }); // build a deposit payload (any token → lsoda*)
11
+ useLeverageYieldWithdraw({ mutationOptions }); // build a withdraw payload (lsoda* → any token; hubWalletSwap)
12
+ useLeverageYieldVaultSwap({ mutationOptions }); // EXECUTE the built payload end-to-end
13
+ useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
14
+
15
+ // Reads
16
+ useLeverageYieldEffectiveApr({ params, queryOptions }); // AAVE + LSD effective net APR (60s)
17
+ useLeverageYieldPosition({ params, queryOptions }); // collateral/debt/ltv/healthFactor/idle (30s)
18
+ useLeverageYieldTotalAssets({ params, queryOptions }); // vault TVL, 18-dp bigint (60s)
19
+ useLeverageYieldPreviewRedeem({ params, queryOptions }); // assets for N shares; price-per-share (60s)
20
+ useLeverageYieldShareBalances({ params, queryOptions }); // per-chain share balances via useQueries (15s)
21
+ ```
22
+
23
+ `deposit` / `withdraw` are **builders** — they assemble a `LeverageYieldSwapPayload`, they do NOT broadcast. Spread the built payload into `useLeverageYieldVaultSwap`'s `mutate`, adding the `walletProvider`. There is no dedicated leverage-yield approve hook: the swap-style deposit approves the spoke-side asset manager, so reuse `useSwapApprove` / `useSwapAllowance` (see Approval pattern).
24
+
25
+ ## Mutation TVars
26
+
27
+ ```ts
28
+ // @ai-snippets-skip
29
+ // deposit — vars are the SDK's deposit params (any token → lsoda* on the hub wallet)
30
+ type UseLeverageYieldDepositVars = LeverageYieldSwapDepositParams;
31
+ // { vault: Address; srcChainKey; srcAddress; inputToken; inputAmount: bigint;
32
+ // minOutputAmount: bigint; deadline?: bigint; solver?: Address; partnerFee? }
33
+
34
+ // withdraw — lsoda* shares → any token on any chain (hub-wallet sourced)
35
+ type UseLeverageYieldWithdrawVars = LeverageYieldSwapWithdrawParams;
36
+ // { vault: Address; srcChainKey; srcAddress; dstChainKey; outputToken;
37
+ // inputAmount: bigint; minOutputAmount: bigint; recipient?; deadline?; solver? }
38
+
39
+ // vaultSwap — the executor. Spread the built payload + walletProvider.
40
+ type UseLeverageYieldVaultSwapVars<K> = Omit<VaultSwapActionParams<K, false>, 'raw'>;
41
+ // = SpokeExecActionParams<K, false, CreateIntentParams<K>> & { hubWalletSwap?; partnerFee? }
42
+ // i.e. { params: CreateIntentParams<K>; walletProvider; hubWalletSwap?; partnerFee?; timeout? }
43
+
44
+ // notifySolver — manual-flow notify step (vaultSwap already notifies internally)
45
+ type UseLeverageYieldNotifySolverVars = SolverExecutionRequest;
46
+ // { intent_tx_hash: Hex } — the hub-side tx hash where the intent landed
47
+ ```
48
+
49
+ ## Read shapes (key picks)
50
+
51
+ ```ts
52
+ // @ai-snippets-skip
53
+ // useLeverageYieldEffectiveApr — AAVE rates + LSD staking yield, leverage re-applied (data unwrapped)
54
+ useLeverageYieldEffectiveApr({ params: { vault } })
55
+ // → UseQueryResult<LeverageYieldEffectiveApr>
56
+ // LeverageYieldEffectiveApr = LeverageYieldApr & { lsdApr, effectiveSupplyAprRay, effectiveNetAprRay }
57
+ // LeverageYieldApr = { supplyAprRay, borrowAprRay, targetLtvBps, leverageMultiplierWad, netAprRay } (RAY = 1e27)
58
+
59
+ // useLeverageYieldPosition — live position snapshot
60
+ useLeverageYieldPosition({ params: { vault } })
61
+ // → UseQueryResult<LeverageYieldPosition>
62
+ // LeverageYieldPosition = { collateral, debt, ltv, healthFactor, idleAsset } (all bigint)
63
+
64
+ // useLeverageYieldPreviewRedeem — assets per shares; pass 1e18 for price-per-share
65
+ useLeverageYieldPreviewRedeem({ params: { vault, shares: 10n ** 18n } })
66
+ // → UseQueryResult<bigint>
67
+
68
+ // useLeverageYieldShareBalances — returns an ARRAY (one query per holder), NOT a single result
69
+ useLeverageYieldShareBalances({ params: { vault, holders } })
70
+ // → UseQueryResult<LeverageYieldShareHolding>[]
71
+ // LeverageYieldShareHolding = { chainKey: SpokeChainKey; holder: Address; shares: bigint }
72
+ // holders: { chainKey: SpokeChainKey; address: string }[] — one row per chain the user may hold under
73
+ ```
74
+
75
+ ## Approval pattern
76
+
77
+ Leverage-yield has **no dedicated approve hook**. A deposit is a swap-style intent that bridges `inputToken` from the spoke chain, so it approves the spoke-side asset manager exactly like a swap — reuse the swap hooks. A withdraw needs no spoke-side approval: the payload carries `hubWalletSwap: true` and `vaultSwap` authorises the hub wallet to spend the `lsoda*` shares via a `Connection.sendMessage` the user signs on `srcChainKey`.
78
+
79
+ | Flow | Token approved | Hook |
80
+ |---|---|---|
81
+ | `deposit` | spoke `inputToken` → asset manager | `useSwapApprove`, `useSwapAllowance` (swap domain) |
82
+ | `withdraw` | none (hub-wallet `sendMessage` authorises the spend) | — |
83
+
84
+ ## Return shapes
85
+
86
+ All read hooks here are **already unwrapped** — they throw on SDK `!ok` so `isError` / `error` / `retry` engage. Read `data` directly; do NOT branch on `data.ok`.
87
+
88
+ | Hook | Returns |
89
+ |---|---|
90
+ | `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` | `SafeUseMutationResult<LeverageYieldSwapPayload, Error, …>` (builder — `data` is the payload to spread into `useLeverageYieldVaultSwap`) |
91
+ | `useLeverageYieldVaultSwap` | `SafeUseMutationResult<VaultSwapResponse, Error, …>` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
92
+ | `useLeverageYieldNotifySolver` | `SafeUseMutationResult<SolverExecutionResponse, Error, …>` (`{ answer: 'OK', intent_hash }`) |
93
+ | `useLeverageYieldEffectiveApr` | `UseQueryResult<LeverageYieldEffectiveApr, Error>` |
94
+ | `useLeverageYieldPosition` | `UseQueryResult<LeverageYieldPosition, Error>` |
95
+ | `useLeverageYieldTotalAssets` | `UseQueryResult<bigint, Error>` |
96
+ | `useLeverageYieldPreviewRedeem` | `UseQueryResult<bigint, Error>` |
97
+ | `useLeverageYieldShareBalances` | `UseQueryResult<LeverageYieldShareHolding, Error>[]` (array — one entry per holder) |
98
+
99
+ ## Gotchas
100
+
101
+ 1. **`deposit` / `withdraw` are builders, not executors.** Their `data` is a `LeverageYieldSwapPayload` — spread it into `useLeverageYieldVaultSwap`'s `mutate` with a `walletProvider` to actually run the swap. Calling them does not broadcast anything.
102
+ 2. **`useLeverageYieldShareBalances` returns an ARRAY, not a single query.** It fans out one `useQueries` row per holder. Aggregate yourself: `balances.reduce((acc, q) => acc + (q.data?.shares ?? 0n), 0n)`. `queryOptions` is spread into every per-holder query (no top-level options slot on `useQueries`).
103
+ 3. **The share-balance key segment is singular: `shareBalance`** (`['leverageYield', 'shareBalance', vault, chainKey, address]`) — one per holder, even though the hook name is plural.
104
+ 4. **Withdraw needs no spoke approval.** Don't gate it on `useSwapAllowance` — the hub-wallet `sendMessage` path approves the share spend internally. Only `deposit` needs the swap-domain allowance/approve pair.
105
+ 5. **Deposit's per-intent `partnerFee` must be reflected in the quote.** If you charge a deposit-only fee (e.g. 1%), `vaultSwap`'s underlying `createVaultIntent` deducts it from `inputAmount` before the swap — quote on the post-fee amount, or `minOutputAmount` becomes unfillable and the intent never settles.
106
+ 6. **`useLeverageYieldVaultSwap` invalidates xBalances on both chains** (`['shared', 'xBalances', srcChainKey]` and `dstChainKey`) on success. Compose your own `onSuccess` after the hook's — it runs first.
107
+ 7. **`useLeverageYieldNotifySolver` is for the manual flow only.** `useLeverageYieldVaultSwap` already notifies the solver internally — only reach for the standalone notify hook when you built the intent with `sodax.leverageYield.createVaultIntent` and relayed it yourself. It does NOT invalidate any queries: its only var is `{ intent_tx_hash }` (no chain context), and the fill lands asynchronously afterward.
108
+
109
+ ## Cross-references
110
+
111
+ - [`../recipes/leverage-yield.md`](../recipes/leverage-yield.md) — full worked deposit / withdraw / reads examples.
112
+ - For the underlying SDK leverage-yield surface (`LeverageYieldService`, `createVaultIntent`, `notifySolver`, APR math), load the `sodax-sdk` skill (integration mode) — its `features/leverage-yield.md`.
@@ -115,4 +115,4 @@ await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
115
115
 
116
116
  - [`../recipes/migration.md`](../recipes/migration.md) — full worked examples.
117
117
  - [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
118
- - `sodax-sdk`: `integration/knowledge/features/icx-bnusd-baln.md` — underlying SDK migration surface.
118
+ - `sodax-sdk`: `integration/knowledge/features/migration.md` — underlying SDK migration surface.
@@ -43,6 +43,8 @@ type UseUserFormattedSummaryParams = ReadHookParams<FormatUserSummaryResponse, {
43
43
  userAddress: string | undefined;
44
44
  }>;
45
45
  // Same shape on useUserReservesData. The hook derives the hub wallet from (spokeChainKey, userAddress) internally.
46
+ // Bitcoin: always pass the personal address as userAddress — the hook transparently resolves to the
47
+ // Bound Exchange trading-wallet-derived hub wallet when a session is active (local lookup, no network).
46
48
 
47
49
  // useAToken — single aToken metadata; FLAT (no chain/user fields)
48
50
  type UseATokenParams = ReadHookParams<ATokenData, {
@@ -57,10 +59,13 @@ type UseATokensBalancesParams = ReadHookParams<Map<Address, bigint>, {
57
59
  userAddress: string | undefined;
58
60
  }>;
59
61
  // Returns a Map keyed by aToken address. The hook resolves the hub wallet from (spokeChainKey, userAddress).
62
+ // Bitcoin: always pass the personal address — trading-wallet resolution is automatic when a session exists.
60
63
  ```
61
64
 
62
65
  > **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.
63
66
 
67
+ > **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.
68
+
64
69
  ## Mutation params
65
70
 
66
71
  All four user mutations share the same TVars shape (only the `action` literal differs):
@@ -132,7 +137,7 @@ if (!isApproved) await approve({ params: supplyParams, walletProvider });
132
137
 
133
138
  ## Gotchas
134
139
 
135
- 1. **Health factor < 1.0 is liquidation territory.** Always render a warning when `useUserFormattedSummary().healthFactor < 1.05` or whatever margin your UX uses.
140
+ 1. **Health factor < 1.0 is liquidation territory.** `healthFactor` is a **string** — coerce before comparing (`summary.healthFactor < 1.05` is a TS type error). A user with **no debt** returns the sentinel `'-1'`, so guard against it or you'll warn on a safe position: `const hf = Number(summary.healthFactor); if (hf !== -1 && hf < 1.05) { /* warn */ }` (use whatever margin your UX needs).
136
141
  2. **Cross-chain delivery via `dstChainKey`/`dstAddress`** — supported on all four actions (supply / withdraw / borrow / repay). Omit for same-chain operations; don't pass `dstChainKey === srcChainKey` (let the default kick in).
137
142
  3. **`useMMAllowance` is `enabled: false` for borrow/withdraw** — `data` stays `undefined` (not `true`). Treat "no allowance result for borrow/withdraw" as "approval not required" — those actions never need ERC-20 approval.
138
143
  4. **Position queries take `{ spokeChainKey, userAddress }`** (NOT `srcChainKey`/`srcAddress` — those are mutation-side names). The hub wallet derivation is automatic.
@@ -91,7 +91,7 @@ type UseStatusParams = ReadHookParams<
91
91
  1. **`Intent.srcChain` and `Intent.dstChain` keep their v1 names.** Even though request-side params use `srcChainKey`/`dstChainKey`, the read-side `Intent` type didn't rename. Don't blanket-replace these names.
92
92
  2. **Default `mutationKey` is `['swap']`.** Use `useIsMutating({ mutationKey: ['swap'] })` to get a global "any swap in flight" state. Override via `mutationOptions.mutationKey` if you want narrower scoping per-call.
93
93
  3. **Quotes auto-refresh every 3s** — pause polling by setting `queryOptions.refetchInterval: false` if the quote is in a non-visible UI.
94
- 4. **Token list has duplicate addresses across chains.** `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens that share a contract address (same token deployed on different chains). When rendering a flat token list, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
94
+ 4. **Token list has duplicate addresses across chains.** `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens that share a contract address (same token deployed on different chains). When rendering a flat token list, use a composite key like `${token.address}-${token.chainKey}` — not `token.address` alone. (`XToken` carries `chainKey`; there is no `blockchain_id` field.)
95
95
 
96
96
  ## Cross-references
97
97
 
@@ -21,11 +21,11 @@ pnpm add @sodax/wallet-sdk-react
21
21
  import { QueryClientProvider } from '@tanstack/react-query';
22
22
  import { SodaxProvider, createSodaxQueryClient } from '@sodax/dapp-kit';
23
23
  import { SodaxWalletProvider, type SodaxWalletConfig } from '@sodax/wallet-sdk-react';
24
- import { ChainKeys, type DeepPartial, type SodaxConfig } from '@sodax/sdk';
24
+ import { ChainKeys, type SodaxOptions } from '@sodax/sdk';
25
25
 
26
26
  const queryClient = createSodaxQueryClient();
27
27
 
28
- const sodaxConfig: DeepPartial<SodaxConfig> = {
28
+ const sodaxConfig: SodaxOptions = {
29
29
  chains: {
30
30
  [ChainKeys.SONIC_MAINNET]: { rpcUrl: 'https://sonic-rpc.publicnode.com' },
31
31
  [ChainKeys.BSC_MAINNET]: { rpcUrl: 'https://bsc-dataseed.binance.org' },
@@ -35,6 +35,7 @@ Copy-paste patterns for adding SODAX features to a React app. Each recipe is sel
35
35
  | [`staking.md`](staking.md) | `useStake`, `useUnstake`, `useClaim`, staking info, ratios |
36
36
  | [`migration.md`](migration.md) | `useMigrateIcxToSoda`, `useRevertMigrateSodaToIcx`, `useMigratebnUSD`, `useMigrateBaln` |
37
37
  | [`dex.md`](dex.md) | `useDexDeposit`, `useSupplyLiquidity`, positions, pools |
38
+ | [`leverage-yield.md`](leverage-yield.md) | `useLeverageYieldDeposit`, `useLeverageYieldWithdraw`, `useLeverageYieldVaultSwap`, APR/position/TVL/share-balance reads |
38
39
  | [`bitcoin.md`](bitcoin.md) | `useRadfiSession`, `useFundTradingWallet`, `useRadfiWithdraw`, UTXO management |
39
40
  | [`backend-queries.md`](backend-queries.md) | Intent tracking, orderbook, money market position queries (read-only, no wallet) |
40
41
 
@@ -31,12 +31,14 @@ Read-only data hooks. No wallet connection required.
31
31
  | `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
32
32
  | `useBackendAllMoneyMarketBorrowers` | All borrowers |
33
33
 
34
- ### Swap Submission
34
+ ### Swaps API (`sodax.api.swaps`)
35
35
 
36
36
  | Hook | Purpose |
37
37
  |------|---------|
38
- | `useBackendSubmitSwapTx` | Submit swap tx to backend |
39
- | `useBackendSubmitSwapTxStatus` | Check submitted swap status |
38
+ | `useSwapsApiSubmitTx` | Submit swap tx to backend |
39
+ | `useSwapsApiSubmitTxStatus` | Check submitted swap status |
40
+
41
+ The full Swaps API v2 surface (quote, allowance, approve, create/submit/cancel intent, fees, gas, …) is wrapped one hook per endpoint under the `useSwapsApi*` prefix — see [hooks-index.md](../reference/hooks-index.md).
40
42
 
41
43
  ## Track Intent
42
44
 
@@ -126,19 +128,20 @@ const { data } = useBackendIntentByTxHash({
126
128
 
127
129
  ## Submit a Swap Tx
128
130
 
129
- `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:
131
+ `useSwapsApiSubmitTx` is a mutation hook. The `request` is a `SubmitTxRequestV2`; per-call config (e.g. backend base URL) flows through `mutate(vars)`, and TanStack Query knobs through the optional `mutationOptions` slot:
130
132
 
131
133
  ```tsx
132
- import { useBackendSubmitSwapTx } from '@sodax/dapp-kit';
134
+ import { useSwapsApiSubmitTx } from '@sodax/dapp-kit';
135
+ import type { SubmitTxRequestV2 } from '@sodax/sdk';
133
136
 
134
- function SubmitButton({ swapPayload, baseURL }) {
135
- const { mutateAsync: submitSwapTx, isPending } = useBackendSubmitSwapTx({
137
+ function SubmitButton({ request, baseURL }: { request: SubmitTxRequestV2; baseURL: string }) {
138
+ const { mutateAsync: submitSwapTx, isPending } = useSwapsApiSubmitTx({
136
139
  mutationOptions: { retry: 5 }, // overrides default retry: 3
137
140
  });
138
141
 
139
142
  const handleSubmit = async () => {
140
143
  const response = await submitSwapTx({
141
- request: swapPayload,
144
+ request,
142
145
  apiConfig: { baseURL }, // per-call backend override
143
146
  });
144
147
  console.log('Submitted:', response);
@@ -148,10 +151,22 @@ function SubmitButton({ swapPayload, baseURL }) {
148
151
  }
149
152
  ```
150
153
 
154
+ Poll the processing status with `useSwapsApiSubmitTxStatus` — it requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) and stops polling on `solved` / `failed`:
155
+
156
+ ```tsx
157
+ import { useSwapsApiSubmitTxStatus } from '@sodax/dapp-kit';
158
+
159
+ function SwapStatus({ txHash, srcChainKey }: { txHash: string; srcChainKey: string }) {
160
+ const { data } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
161
+ return <span>{data?.data?.status ?? 'idle'}</span>;
162
+ }
163
+ ```
164
+
151
165
  ## Default Polling
152
166
 
153
167
  | Hook | Interval |
154
168
  |------|---------|
155
169
  | `useBackendIntentByTxHash` | 1s |
170
+ | `useSwapsApiSubmitTxStatus` | 1s (stops on `solved` / `failed`) |
156
171
  | `useBackendOrderbook` | none (`staleTime: 30s`, no auto-refetch) |
157
172
  | Others | No auto-refresh |
@@ -1,6 +1,6 @@
1
- # Recipe: Bitcoin (Radfi)
1
+ # Recipe: Bitcoin (Bound Exchange)
2
2
 
3
- Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
3
+ Bitcoin trading via the Bound Exchange protocol. Authenticate, fund a trading wallet, trade, withdraw, and manage UTXOs.
4
4
 
5
5
  **Depends on:** [setup.md](setup.md), [wallet-connectivity.md](wallet-connectivity.md)
6
6
 
@@ -10,7 +10,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
10
10
 
11
11
  | Hook | Type | Purpose |
12
12
  |------|------|---------|
13
- | `useRadfiAuth` | Mutation | Authenticate with Radfi via BIP322 signing |
13
+ | `useRadfiAuth` | Mutation | Authenticate with Bound Exchange via BIP322 signing |
14
14
  | `useRadfiSession` | Utility | Manage full session lifecycle (login, refresh, auto-refresh) |
15
15
  | `useTradingWallet` | Utility | Get trading wallet address from persisted session (synchronous) |
16
16
 
@@ -19,7 +19,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
19
19
  | Hook | Type | Purpose |
20
20
  |------|------|---------|
21
21
  | `useBitcoinBalance` | Query | BTC balance for any address (sums UTXOs from mempool.space) |
22
- | `useTradingWalletBalance` | Query | Trading wallet balance from Radfi API (confirmed + pending) |
22
+ | `useTradingWalletBalance` | Query | Trading wallet balance from Bound Exchange API (confirmed + pending) |
23
23
 
24
24
  ### Operations
25
25
 
@@ -32,7 +32,7 @@ Bitcoin trading via the Radfi protocol. Authenticate, fund a trading wallet, tra
32
32
 
33
33
  ## Session Flow
34
34
 
35
- Radfi requires authentication before any trading operation. The typical flow:
35
+ Bound Exchange requires authentication before any trading operation. The typical flow:
36
36
 
37
37
  ```tsx
38
38
  import { useRadfiSession } from '@sodax/dapp-kit';
@@ -49,7 +49,7 @@ function BitcoinAuth() {
49
49
 
50
50
  return (
51
51
  <button onClick={login} disabled={isLoginPending}>
52
- {isLoginPending ? 'Signing...' : 'Login to Radfi'}
52
+ {isLoginPending ? 'Signing...' : 'Login to Bound Exchange'}
53
53
  </button>
54
54
  );
55
55
  }
@@ -77,7 +77,7 @@ function BitcoinBalances({ walletAddress }: { walletAddress: string }) {
77
77
  params: { address: walletAddress },
78
78
  });
79
79
 
80
- // Trading wallet balance (from Radfi API). `RadfiWalletBalance` fields:
80
+ // Trading wallet balance (from Bound Exchange API). `RadfiWalletBalance` fields:
81
81
  // `btcSatoshi`, `pendingSatoshi`, `externalPendingSatoshi`, `totalUtxos`.
82
82
  const { data: tradingBalance } = useTradingWalletBalance({
83
83
  params: { walletProvider, tradingAddress },
@@ -188,6 +188,6 @@ function UtxoManager({ tradingAddress }: { tradingAddress: string }) {
188
188
 
189
189
  - **Authentication required** before any trading operation. `useRadfiSession` manages this automatically.
190
190
  - **Trading wallet** is created during first authentication — not a separate step.
191
- - **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Radfi session from localStorage.
191
+ - **`useTradingWallet(walletAddress)`** is a synchronous utility (no network call) — it reads the persisted Bound Exchange session from localStorage.
192
192
  - **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.
193
193
  - **Session tokens** are stored in localStorage keyed by wallet address. They're for API rate-limiting, not for accessing user assets.