@sodax/skills 2.0.0-rc.18 → 2.0.0-rc.20

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 (107) hide show
  1. package/AGENTS.md +3 -3
  2. package/package.json +1 -1
  3. package/skills/sodax-dapp-kit/auxiliary-services/SKILL.md +3 -3
  4. package/skills/sodax-dapp-kit/bridge/SKILL.md +3 -3
  5. package/skills/sodax-dapp-kit/integration/knowledge/features/auxiliary-services.md +22 -7
  6. package/skills/sodax-dapp-kit/integration/knowledge/features/dex.md +2 -2
  7. package/skills/sodax-dapp-kit/integration/knowledge/features/money-market.md +1 -1
  8. package/skills/sodax-dapp-kit/integration/knowledge/features/swap.md +1 -1
  9. package/skills/sodax-dapp-kit/integration/knowledge/recipes/backend-queries.md +23 -8
  10. package/skills/sodax-dapp-kit/integration/knowledge/recipes/migration.md +1 -1
  11. package/skills/sodax-dapp-kit/integration/knowledge/recipes/setup.md +1 -1
  12. package/skills/sodax-dapp-kit/integration/knowledge/recipes/swap.md +1 -1
  13. package/skills/sodax-dapp-kit/integration/knowledge/reference/hooks-index.md +41 -3
  14. package/skills/sodax-dapp-kit/integration/knowledge/reference/querykey-conventions.md +32 -0
  15. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/breaking-changes/sdk-leakage.md +1 -1
  16. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/auxiliary-services.md +9 -7
  17. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/bridge.md +1 -1
  18. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/dex.md +1 -1
  19. package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/reference/renamed-hooks.md +1 -1
  20. package/skills/sodax-dapp-kit/money-market/SKILL.md +1 -1
  21. package/skills/sodax-dapp-kit/swap/SKILL.md +2 -2
  22. package/skills/sodax-sdk/SKILL.md +6 -5
  23. package/skills/sodax-sdk/backend-api/SKILL.md +17 -15
  24. package/skills/sodax-sdk/dex/SKILL.md +1 -1
  25. package/skills/sodax-sdk/integration/knowledge/ai-rules.md +1 -1
  26. package/skills/sodax-sdk/integration/knowledge/architecture.md +15 -14
  27. package/skills/sodax-sdk/integration/knowledge/chain-specifics.md +22 -2
  28. package/skills/sodax-sdk/integration/knowledge/features/backend-api.md +21 -16
  29. package/skills/sodax-sdk/integration/knowledge/features/bridge.md +14 -14
  30. package/skills/sodax-sdk/integration/knowledge/features/dex.md +7 -7
  31. package/skills/sodax-sdk/integration/knowledge/features/migration.md +73 -28
  32. package/skills/sodax-sdk/integration/knowledge/features/money-market.md +19 -25
  33. package/skills/sodax-sdk/integration/knowledge/features/partner.md +5 -4
  34. package/skills/sodax-sdk/integration/knowledge/features/recovery.md +5 -4
  35. package/skills/sodax-sdk/integration/knowledge/features/staking.md +2 -2
  36. package/skills/sodax-sdk/integration/knowledge/features/swap.md +23 -22
  37. package/skills/sodax-sdk/integration/knowledge/features/swaps-api.md +171 -0
  38. package/skills/sodax-sdk/integration/knowledge/recipes/backend-server-init.md +3 -3
  39. package/skills/sodax-sdk/integration/knowledge/recipes/gas-estimation.md +8 -4
  40. package/skills/sodax-sdk/integration/knowledge/recipes/initialize-sodax.md +29 -1
  41. package/skills/sodax-sdk/integration/knowledge/recipes/raw-tx-flow.md +3 -4
  42. package/skills/sodax-sdk/integration/knowledge/recipes/result-and-errors.md +1 -1
  43. package/skills/sodax-sdk/integration/knowledge/recipes/testing.md +7 -11
  44. package/skills/sodax-sdk/integration/knowledge/reference/README.md +1 -1
  45. package/skills/sodax-sdk/integration/knowledge/reference/chain-keys.md +5 -4
  46. package/skills/sodax-sdk/integration/knowledge/reference/error-codes.md +15 -8
  47. package/skills/sodax-sdk/integration/knowledge/reference/glossary.md +2 -2
  48. package/skills/sodax-sdk/integration/knowledge/reference/public-api.md +12 -3
  49. package/skills/sodax-sdk/migration/SKILL.md +1 -1
  50. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/README.md +1 -1
  51. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/ai-rules.md +1 -1
  52. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/architecture.md +2 -2
  53. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md +3 -3
  54. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/breaking-changes/type-system.md +6 -5
  55. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/checklist.md +1 -1
  56. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/backend-api.md +23 -23
  57. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/bridge.md +5 -5
  58. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/dex.md +2 -4
  59. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/migration.md +29 -27
  60. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/money-market.md +2 -2
  61. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/partner.md +10 -5
  62. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/recovery.md +2 -2
  63. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/staking.md +2 -2
  64. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/features/swap.md +22 -18
  65. package/skills/sodax-sdk/migration-v1-to-v2/knowledge/reference/sodax-config.md +7 -7
  66. package/skills/sodax-sdk/money-market/SKILL.md +3 -3
  67. package/skills/sodax-sdk/recovery/SKILL.md +1 -1
  68. package/skills/sodax-sdk/swap/SKILL.md +4 -3
  69. package/skills/sodax-sdk/swaps-api/SKILL.md +62 -0
  70. package/skills/sodax-wallet-sdk-core/SKILL.md +2 -2
  71. package/skills/sodax-wallet-sdk-core/bitcoin/SKILL.md +1 -1
  72. package/skills/sodax-wallet-sdk-core/evm/SKILL.md +3 -3
  73. package/skills/sodax-wallet-sdk-core/icon/SKILL.md +4 -4
  74. package/skills/sodax-wallet-sdk-core/injective/SKILL.md +2 -2
  75. package/skills/sodax-wallet-sdk-core/integration/knowledge/README.md +1 -1
  76. package/skills/sodax-wallet-sdk-core/integration/knowledge/ai-rules.md +1 -1
  77. package/skills/sodax-wallet-sdk-core/integration/knowledge/architecture.md +5 -5
  78. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/bitcoin.md +2 -2
  79. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/evm.md +2 -2
  80. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/icon.md +5 -5
  81. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/injective.md +4 -2
  82. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/near.md +1 -1
  83. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/solana.md +2 -2
  84. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stacks.md +2 -2
  85. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/stellar.md +2 -2
  86. package/skills/sodax-wallet-sdk-core/integration/knowledge/features/sui.md +1 -1
  87. package/skills/sodax-wallet-sdk-core/integration/knowledge/quickstart.md +1 -1
  88. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/setup-private-key.md +2 -2
  89. package/skills/sodax-wallet-sdk-core/integration/knowledge/recipes/sign-and-broadcast.md +1 -0
  90. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/chain-support.md +3 -2
  91. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/interfaces.md +7 -5
  92. package/skills/sodax-wallet-sdk-core/integration/knowledge/reference/provider-classes.md +2 -2
  93. package/skills/sodax-wallet-sdk-core/stellar/SKILL.md +1 -1
  94. package/skills/sodax-wallet-sdk-react/connect/SKILL.md +1 -1
  95. package/skills/sodax-wallet-sdk-react/integration/knowledge/architecture.md +3 -3
  96. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/chain-detection.md +1 -1
  97. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/connect-button.md +1 -1
  98. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/sign-message.md +10 -10
  99. package/skills/sodax-wallet-sdk-react/integration/knowledge/recipes/switch-chain.md +1 -1
  100. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/api-surface.md +3 -3
  101. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/chain-support.md +4 -4
  102. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/connectors.md +1 -1
  103. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/hooks.md +5 -4
  104. package/skills/sodax-wallet-sdk-react/integration/knowledge/reference/wallet-brands.md +1 -1
  105. package/skills/sodax-wallet-sdk-react/migration-v1-to-v2/knowledge/recipes/multi-chain-modal.md +57 -31
  106. package/skills/sodax-wallet-sdk-react/sign-message/SKILL.md +1 -1
  107. package/skills/sodax-wallet-sdk-react/wallet-modal/SKILL.md +1 -1
package/AGENTS.md CHANGED
@@ -10,7 +10,7 @@ This package ships **mode-gated broad SDK skills** (`skills/<name>/SKILL.md`, on
10
10
 
11
11
  | SDK package | Broad skill | Granular per-feature skills |
12
12
  |---|---|---|
13
- | `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
13
+ | `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/leverage-yield`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api`, `sodax-sdk/swaps-api` |
14
14
  | `@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` |
15
15
  | `@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` |
16
16
  | `@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/leverage-yield`, `sodax-dapp-kit/migration`, `sodax-dapp-kit/bitcoin`, `sodax-dapp-kit/auxiliary-services` |
@@ -26,7 +26,7 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
26
26
  | Consumer is… | Load skills (mode) |
27
27
  |---|---|
28
28
  | **Not sure what to build / not a developer** (no SDK, feature, or concrete product chosen yet) | `sodax-build` (front-door ideation: interview → product brief → handoff; it names the dev skills to load next). Skip the moment any SDK / feature / hook is named |
29
- | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, 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 |
29
+ | **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, leverage-yield, migration, partner, recovery, backend-api, swaps-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 |
30
30
  | **Scaffolding ONE specific dapp-kit feature in React** (swap, money-market, staking, bridge, dex, leverage-yield, 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 |
31
31
  | **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 |
32
32
  | **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 |
@@ -63,7 +63,7 @@ packages/skills/
63
63
  ├── sodax-build/ {SKILL.md, knowledge/ (flat)} — cross-cutting front-door / ideation skill; no mode split, no granular children
64
64
  ├── sodax-sdk/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
65
65
  │ <feature>/SKILL.md children — swap, money-market, bridge, staking, dex,
66
- │ leverage-yield, migration, partner, recovery, backend-api}
66
+ │ leverage-yield, migration, partner, recovery, backend-api, swaps-api}
67
67
  ├── sodax-wallet-sdk-core/ {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
68
68
  │ <chain>/SKILL.md children — evm, solana, sui, bitcoin, stellar, icon,
69
69
  │ injective, near, stacks}
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.0.0-rc.18",
7
+ "version": "2.0.0-rc.20",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-dapp-kit-auxiliary-services
3
- 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.'
3
+ 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), the Swaps API v2 client hooks (useSwapsApiQuote, useSwapsApiSubmitTx, useSwapsApiStatus), 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.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -17,7 +17,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
17
17
  2. **Which surface?**
18
18
  - **Partner fees:** `useIsTokenApproved` → `useApproveToken` → `useSetSwapPreference` → `useFeeClaimSwap` (returns `IntentAutoSwapResult`, NOT `SwapResponse`); `useGetAutoSwapPreferences`, `useFetchAssetsBalances` for reads.
19
19
  - **Recovery:** `useHubAssetBalances` (list stuck hub assets) → `useWithdrawHubAsset` (withdraw one back to a spoke). Follows a *known* failed cross-chain op — investigate the failure first.
20
- - **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`).
20
+ - **Backend reads (no wallet):** intent tracking (`useBackendIntentByTxHash` polls 1s, `useBackendIntentByHash`, `useBackendUserIntents`), orderbook (`useBackendOrderbook` — `pagination` nests under `params`), MM data (`useBackendMoneyMarketPosition` etc.), and the Swaps API v2 client (`useSwapsApi*` — e.g. `useSwapsApiSubmitTx`, `useSwapsApiSubmitTxStatus`, `useSwapsApiQuote`).
21
21
  - **Shared utilities:** `useSodaxContext`, `useHubProvider`, `useXBalances` (needs `xService` from wallet-sdk-react), `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`, `useEstimateGas`, `useStellarTrustlineCheck` / `useRequestTrustline`.
22
22
 
23
23
  ## Integration workflow (new v2 code)
@@ -55,7 +55,7 @@ Granular skill for the smaller `@sodax/dapp-kit` v2 surfaces grouped together: *
55
55
 
56
56
  ## Related granular skills (same family)
57
57
 
58
- - [`../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.
58
+ - [`../swap/SKILL.md`](../swap/SKILL.md) — `useSwapsApiSubmitTx` + intent tracking are the backend half of the step-by-step swap flow; partner fee-claim reuses the swap intent layer.
59
59
  - [`../money-market/SKILL.md`](../money-market/SKILL.md) — backend MM reads complement the on-chain MM action hooks.
60
60
 
61
61
  For multi-feature tasks, load the broad [`sodax-dapp-kit` skill](../SKILL.md).
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-dapp-kit-bridge
3
- 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.'
3
+ 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 / srcAsset→srcToken / dstAsset→dstToken, new required srcAddress, recipient unchanged, mutateAsyncSafe). Links into the parent sodax-dapp-kit knowledge tree. For backend/Node, use the sodax-sdk skill.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -38,14 +38,14 @@ Granular skill for the bridge hooks of `@sodax/dapp-kit` v2. queryKey/mutationKe
38
38
 
39
39
  1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT (read first).
40
40
  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).
41
- 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`).
41
+ 3. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — `useBridge` param renames (`srcChainId` → `srcChainKey`, `dstChainId` → `dstChainKey`, `srcAsset` → `srcToken`, `dstAsset` → `dstToken`; new required `srcAddress`; `recipient` is UNCHANGED — NOT renamed to `dstAddress`); `useGetBridgeableAmount` shape change (bigint → `BridgeLimit`).
42
42
 
43
43
  ## Verification
44
44
 
45
45
  1. `pnpm tsc --noEmit` clean.
46
46
  2. `useBridge` consumers destructure `{ srcChainTxHash, dstChainTxHash }` (no array/string).
47
47
  3. `useGetBridgeableAmount` consumers read `data.amount` (not a scalar).
48
- 4. No `useSpokeProvider`, no `srcChainId`/`recipient` v1 field names (migration only).
48
+ 4. No `useSpokeProvider`, no `srcChainId`/`srcAsset`/`dstAsset` v1 field names (migration only); `recipient` stays `recipient` (do NOT rename to `dstAddress`).
49
49
 
50
50
  ## Related granular skills (same family)
51
51
 
@@ -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)`.
68
70
 
69
71
  ```ts
70
72
  // @ai-snippets-skip
71
- useBackendSubmitSwapTx({ mutationOptions }); // Mutation
72
- useBackendSubmitSwapTxStatus({ params, queryOptions }); // Query — check submitted status
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
73
76
  ```
74
77
 
75
- `useBackendSubmitSwapTx` is a mutation hook — per-call config (e.g. backend base URL) flows through `mutate(vars)`:
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 }`):
76
79
 
77
80
  ```ts
78
81
  // @ai-snippets-skip
79
- const { mutateAsync: submitSwapTx } = useBackendSubmitSwapTx();
80
- await submitSwapTx({ request: swapPayload, apiConfig: { baseURL: 'https://...' } });
82
+ const { mutateAsync: submitSwapTx } = useSwapsApiSubmitTx();
83
+ // request: SubmitTxRequestV2 — relayData is the string payload; intent carries bigint fields
84
+ await submitSwapTx({ request, apiConfig: { baseURL: 'https://...' } });
81
85
  ```
82
86
 
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:
88
+
89
+ ```ts
90
+ // @ai-snippets-skip
91
+ const { data: status } = useSwapsApiSubmitTxStatus({ params: { txHash, srcChainKey } });
92
+ // status?.data?.status: 'pending' | 'relaying' | 'relayed' | 'posting_execution' | 'posted_execution' | 'solved' | 'failed'
93
+ ```
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.
@@ -193,7 +207,8 @@ The underlying SDK methods (`isStorageRegistered` / `registerStorage` on the NEA
193
207
  | Hook | Polling | Notes |
194
208
  |---|---|---|
195
209
  | `useBackendIntentByTxHash` | 1s | once a `txHash` is supplied (refetch is unconditional, not "while pending") |
196
- | `useBackendSubmitSwapTxStatus` | varies | poll stops on `executed` / `failed` |
210
+ | `useSwapsApiSubmitTxStatus` | 1s | requires `txHash` + `srcChainKey`; stops on `solved` / `failed` |
211
+ | `useSwapsApiStatus` | 1s | solver intent status; stops on status `3` / `4` |
197
212
  | `useBackendOrderbook` | none | `staleTime: 30s` — fresh-window, no background refetch |
198
213
  | `useExpiredUtxos` (bitcoin) | 60s | refetchInterval |
199
214
  | `useQuote` (swap) | 3s | refetchInterval |
@@ -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
  ```
@@ -137,7 +137,7 @@ if (!isApproved) await approve({ params: supplyParams, walletProvider });
137
137
 
138
138
  ## Gotchas
139
139
 
140
- 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).
141
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).
142
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.
143
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
 
@@ -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 |
@@ -208,5 +208,5 @@ function BnUSDMigration({ srcAddress }: { srcAddress: string }) {
208
208
 
209
209
  - **ICX and BALN forward migrations** don't require approval — ICON has no ERC-20 allowance mechanism.
210
210
  - **SODA → ICX revert** and **EVM/Stellar bnUSD sources** require approval before migrating.
211
- - **BALN lock periods**: `0` = 0.5x reward, `6` = 0.75x, `12` = 1.0x, `24` = 1.5x (months).
211
+ - **BALN lock periods** (months → reward multiplier): `0` = 0.5x, `6` = 0.75x, `12` = 1.0x, `18` = 1.25x, `24` = 1.5x. Pass the `LockupPeriod` enum (whose values are in seconds), not the raw month number.
212
212
  - `useMigratebnUSD` is bidirectional — swap `srcbnUSD`/`dstbnUSD` and `srcChainKey`/`dstChainKey` to go the other direction.
@@ -162,7 +162,7 @@ ChainKeys.INJECTIVE_MAINNET; // 'injective-1'
162
162
  ChainKeys.NEAR_MAINNET; // 'near'
163
163
  ChainKeys.STACKS_MAINNET; // 'stacks'
164
164
  ChainKeys.BITCOIN_MAINNET; // 'bitcoin'
165
- // HyperEVM, Lightlink, Redbelly, Kaia also available.
165
+ // HyperEVM, Lightlink, Redbelly, Kaia, Hedera also available.
166
166
  ```
167
167
 
168
168
  **v1 → v2:** the legacy `*_MAINNET_CHAIN_ID` constants (e.g. `BSC_MAINNET_CHAIN_ID`) are gone. Use `ChainKeys.X_MAINNET` namespace access.
@@ -246,7 +246,7 @@ console.log({ swap, isError, error, swapsInFlight });
246
246
 
247
247
  ### Token list has duplicate addresses
248
248
 
249
- `getSupportedSolverTokens()` can return multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.blockchain_id}` — not `token.address` alone.
249
+ `sodax.swaps.getSupportedSwapTokens()` returns `Record<SpokeChainKey, readonly XToken[]>`. Flattening it (e.g. `Object.values(...).flat()`) yields multiple tokens sharing the same contract address (same token on different chains). When rendering token lists, use a composite key like `${token.address}-${token.chainKey}` — not `token.address` alone. (`XToken` carries `chainKey`; there is no `blockchain_id` field.)
250
250
 
251
251
  ### Balance display
252
252
 
@@ -147,13 +147,11 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
147
147
  | `useBackendIntentByHash` | none |
148
148
  | `useBackendUserIntents` | none |
149
149
 
150
- ### Orderbook + swap submission
150
+ ### Orderbook
151
151
 
152
152
  | Hook | Type / Polling |
153
153
  |---|---|
154
154
  | `useBackendOrderbook` | Query; `staleTime: 30s` — fresh-window only, no background refetch |
155
- | `useBackendSubmitSwapTx` | Mutation |
156
- | `useBackendSubmitSwapTxStatus` | Query; polls until `executed` / `failed` |
157
155
 
158
156
  ### Money market data
159
157
 
@@ -166,6 +164,46 @@ Comprehensive hook table across 12 feature domains. Use this when you know the f
166
164
  | `useBackendMoneyMarketAssetBorrowers` | Borrowers for an asset |
167
165
  | `useBackendAllMoneyMarketBorrowers` | All borrowers |
168
166
 
167
+ ## Swaps API (`sodax.api.swaps`)
168
+
169
+ Typed React Query wrappers over the backend Swaps API v2 (`sodax.api.swaps.*`), one per endpoint. Distinct from the on-chain `swap/` hooks (`useQuote`/`useStatus`/`useSwap`/…), which drive `sodax.swaps` (the `SwapService`).
170
+
171
+ ### Tokens · quote · fees · gas (reads)
172
+
173
+ | Hook | Type / Polling |
174
+ |---|---|
175
+ | `useSwapsApiTokens` | Query; all supported swap tokens by chain |
176
+ | `useSwapsApiTokensByChain` | Query; tokens for one chain |
177
+ | `useSwapsApiQuote` | Query; solver quote (set `query.includeTxData` for `txData`) |
178
+ | `useSwapsApiDeadline` | Query; computed swap deadline |
179
+ | `useSwapsApiPartnerFee` | Query; partner fee for an amount |
180
+ | `useSwapsApiSolverFee` | Query; protocol (solver) fee for an amount |
181
+ | `useSwapsApiEstimateGas` | Query; gas estimate for a raw tx |
182
+
183
+ ### Intent lifecycle (reads)
184
+
185
+ | Hook | Type / Polling |
186
+ |---|---|
187
+ | `useSwapsApiAllowance` | Query; `{ valid }` allowance check |
188
+ | `useSwapsApiStatus` | Query (1s); polls until status `3` (SOLVED) / `4` (FAILED) |
189
+ | `useSwapsApiIntentHash` | Query; keccak256 of an intent struct |
190
+ | `useSwapsApiIntentPacket` | Query; long-polls the relayer for the fill packet (no client interval) |
191
+ | `useSwapsApiIntentExtraData` | Query; relay extra-data for submit |
192
+ | `useSwapsApiFilledIntent` | Query; on-chain fill state by tx hash |
193
+ | `useSwapsApiIntent` | Query; decoded intent struct by tx hash |
194
+ | `useSwapsApiSubmitTxStatus` | Query (1s); requires `txHash` + `srcChainKey`; polls until `solved` / `failed` |
195
+
196
+ ### Actions (mutations)
197
+
198
+ | Hook | Type |
199
+ |---|---|
200
+ | `useSwapsApiApprove` | Mutation; builds unsigned approval tx |
201
+ | `useSwapsApiCreateIntent` | Mutation; builds `{ tx, intent, relayData }` |
202
+ | `useSwapsApiSubmitIntent` | Mutation; submits broadcast intent to the relay |
203
+ | `useSwapsApiCancelIntent` | Mutation; builds unsigned cancel tx |
204
+ | `useSwapsApiCreateLimitOrder` | Mutation; builds limit-order intent tx |
205
+ | `useSwapsApiSubmitTx` | Mutation; `request: SubmitTxRequestV2` |
206
+
169
207
  ## Partner
170
208
 
171
209
  | Hook | Type | Purpose |
@@ -150,6 +150,38 @@ Skip if you're writing a feature hook for the first time and want to align with
150
150
  | `['staking', 'cancelUnstake']` | `useCancelUnstake` |
151
151
  | `['staking', 'approve', 'stake' \| 'unstake' \| 'instantUnstake']` | `useStakeApprove` / `useUnstakeApprove` / `useInstantUnstakeApprove` |
152
152
 
153
+ ### Backend (read)
154
+
155
+ Backend read hooks (`useBackendIntentByTxHash`, `useBackendIntentByHash`, `useBackendUserIntents`, `useBackendOrderbook`, `useBackendMoneyMarketPosition`, …) follow the `['backend', action, ...]` shape — see the source hook files.
156
+
157
+ ### Swaps API (`sodax.api.swaps`)
158
+
159
+ Typed wrappers over `sodax.api.swaps.*` (one per Swaps API v2 endpoint), all keyed `['swapsApi', action, ...]`.
160
+
161
+ | Key | Hook |
162
+ |---|---|
163
+ | `['swapsApi', 'tokens']` | `useSwapsApiTokens` |
164
+ | `['swapsApi', 'tokens', chainKey]` | `useSwapsApiTokensByChain` |
165
+ | `['swapsApi', 'quote', …]` | `useSwapsApiQuote` |
166
+ | `['swapsApi', 'deadline', …]` | `useSwapsApiDeadline` |
167
+ | `['swapsApi', 'allowance', …]` | `useSwapsApiAllowance` |
168
+ | `['swapsApi', 'status', …]` | `useSwapsApiStatus` |
169
+ | `['swapsApi', 'intentHash', …]` | `useSwapsApiIntentHash` |
170
+ | `['swapsApi', 'intentPacket', …]` | `useSwapsApiIntentPacket` |
171
+ | `['swapsApi', 'intentExtraData', …]` | `useSwapsApiIntentExtraData` |
172
+ | `['swapsApi', 'filledIntent', txHash]` | `useSwapsApiFilledIntent` |
173
+ | `['swapsApi', 'intent', txHash]` | `useSwapsApiIntent` |
174
+ | `['swapsApi', 'estimateGas', …]` | `useSwapsApiEstimateGas` |
175
+ | `['swapsApi', 'partnerFee', amount]` | `useSwapsApiPartnerFee` |
176
+ | `['swapsApi', 'solverFee', amount]` | `useSwapsApiSolverFee` |
177
+ | `['swapsApi', 'submitTx', 'status', txHash, srcChainKey]` | `useSwapsApiSubmitTxStatus` — both identifiers required |
178
+ | `['swapsApi', 'approve']` | `useSwapsApiApprove` mutation |
179
+ | `['swapsApi', 'createIntent']` | `useSwapsApiCreateIntent` mutation |
180
+ | `['swapsApi', 'submitIntent']` | `useSwapsApiSubmitIntent` mutation |
181
+ | `['swapsApi', 'cancelIntent']` | `useSwapsApiCancelIntent` mutation |
182
+ | `['swapsApi', 'createLimitOrder']` | `useSwapsApiCreateLimitOrder` mutation |
183
+ | `['swapsApi', 'submitTx']` | `useSwapsApiSubmitTx` mutation |
184
+
153
185
  ### Leverage Yield
154
186
 
155
187
  | Key | Hook |
@@ -131,7 +131,7 @@ If your dapp-kit consumer code catches errors from mutations and uses `instanceo
131
131
  + }
132
132
  ```
133
133
 
134
- `isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 13 reason-only codes.
134
+ `isSodaxError` is re-exported from `@sodax/dapp-kit`. Discriminate via `(error.feature, error.code)` — the feature is now a first-class field, and the code vocabulary is unified to 14 reason-only codes (`'USER_REJECTED'` is reachable from any orchestrator that wraps a wallet sign step, which lets consumers render a "Cancelled" UI distinct from real failures).
135
135
 
136
136
  Full SDK-level detail: `sodax-sdk`: `migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md`.
137
137
 
@@ -44,15 +44,17 @@ Read-only. No `walletProvider` involved. Convert to single-object query shape.
44
44
  + const { data: assets } = useBackendAllMoneyMarketAssets({});
45
45
  ```
46
46
 
47
- `useBackendSubmitSwapTx` is a mutation — per-call config flows through `mutate(vars)`:
47
+ `useSwapsApiSubmitTx` (v1: `useBackendSubmitSwapTx` — renamed and moved into the `swapsApi/` namespace) is a mutation — per-call config flows through `mutate(vars)`. The v2 `request` is a `SubmitTxRequestV2` (`{ txHash, srcChainKey, walletAddress, intent, relayData }`):
48
48
 
49
49
  ```diff
50
50
  - const submit = useBackendSubmitSwapTx({ baseURL: 'https://...' }); // v1: per-instance config
51
51
  - await submit.mutateAsync(swapPayload);
52
- + const { mutateAsync: submit } = useBackendSubmitSwapTx();
52
+ + const { mutateAsync: submit } = useSwapsApiSubmitTx();
53
53
  + await submit({ request: swapPayload, apiConfig: { baseURL: 'https://...' } }); // v2: per-call config
54
54
  ```
55
55
 
56
+ `useSwapsApiSubmitTxStatus` (v1: `useBackendSubmitSwapTxStatus`) now requires **both** `txHash` and `srcChainKey` (the v2 status endpoint needs the source chain key) — a v1 call that passed only a tx hash won't run until `srcChainKey` is supplied. The full Swaps API v2 surface is now wrapped as `useSwapsApi*` hooks (see the integration `hooks-index`).
57
+
56
58
  ## Shared utilities
57
59
 
58
60
  ### `useXBalances`
@@ -77,26 +79,26 @@ Note: the request param is still `xChainId` (not renamed to `chainKey`). This is
77
79
  - const estimate = useEstimateGas(walletProvider);
78
80
  - await estimate.mutateAsync({ rawTx });
79
81
  + const { mutateAsyncSafe: estimateGas } = useEstimateGas();
80
- + const result = await estimateGas({ rawTx, walletProvider });
82
+ + const result = await estimateGas({ tx, chainKey }); // TVars is EstimateGasParams<C> = { tx, chainKey } — no walletProvider
81
83
  ```
82
84
 
83
85
  ### `useStellarTrustlineCheck` / `useRequestTrustline`
84
86
 
85
87
  ```diff
86
88
  - const { data: hasTrustline } = useStellarTrustlineCheck(account, asset);
87
- + const { data: hasTrustline } = useStellarTrustlineCheck({ params: { account, asset } });
89
+ + const { data: hasTrustline } = useStellarTrustlineCheck({ params: { token, amount, chainId, walletProvider } });
88
90
 
89
91
  - const request = useRequestTrustline(walletProvider);
90
92
  - await request.mutateAsync({ account, asset });
91
- + const { mutateAsync: request } = useRequestTrustline();
92
- + await request({ account, asset, walletProvider });
93
+ + const { requestTrustline } = useRequestTrustline(token); // positional token arg; NOT a mutation hook
94
+ + await requestTrustline({ token, amount, srcChainKey, walletProvider });
93
95
  ```
94
96
 
95
97
  ### `useDeriveUserWalletAddress` / `useGetUserHubWalletAddress`
96
98
 
97
99
  ```diff
98
100
  - const { data: hubAddress } = useDeriveUserWalletAddress(spokeChainKey, srcAddress);
99
- + const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainKey, srcAddress } });
101
+ + const { data: hubAddress } = useDeriveUserWalletAddress({ params: { spokeChainId, spokeAddress } });
100
102
  ```
101
103
 
102
104
  ## Pitfalls
@@ -151,7 +151,7 @@ The hook equivalence in code:
151
151
  1. **`useGetBridgeableAmount` data shape changed.** v1 returned bare `bigint`; v2 returns `Result<BridgeLimit>` where `BridgeLimit = { amount, decimals, type }`. UI code that displayed the bigint directly needs `.value.amount`.
152
152
  2. **Tokens must share the same vault** to be bridgeable. Use `useGetBridgeableTokens` to enumerate compatible destinations — passing an incompatible pair to `bridge()` rejects with `VALIDATION_FAILED`.
153
153
  3. **`useBridge` return is `TxHashPair`** — destructure as `{ srcChainTxHash, dstChainTxHash }`, not `[a, b]`.
154
- 4. **`recipient` field renamed to `dstAddress`** for consistency with the rest of the SDK.
154
+ 4. **`recipient` is NOT renamed.** It stays `recipient` in v2 (the destination receiver). Don't be tempted to rename it to `dstAddress` — that field shape lives on money-market params, not bridge. The genuinely new field is `srcAddress` (the spoke-side sender), which v1 didn't require.
155
155
 
156
156
  ## Cross-references
157
157
 
@@ -9,7 +9,7 @@ Pair: [`features/dex.md`](../../../integration/knowledge/features/dex.md).
9
9
  1. **All mutations** (`useDexDeposit`, `useDexWithdraw`, `useSupplyLiquidity`, `useDecreaseLiquidity`, `useClaimRewards`, `useDexApprove`) — single-object hook init + `mutate({ params, walletProvider })`. SDK-leakage adds required `srcChainKey` + `srcAddress` to all action params.
10
10
  2. **`useSupplyLiquidity` handles both mint-new and increase-existing** — pass `tokenId` in params for increase, omit for mint. Use `useCreateSupplyLiquidityParams` to handle the routing.
11
11
  3. **`usePools` returns synchronously** in the SDK. The hook still returns `UseQueryResult` but the underlying call is config-derived (no RPC) — `staleTime: Infinity`, no auto-refresh.
12
- 4. **Param builders take a FLAT props object** — `useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams` — NOT `{ params: { ... } }`-wrapped. Their inputs use `srcChainKey` (not `srcChainId`); the result is spread into the mutation's `params` field at the call site.
12
+ 4. **Param builders take a FLAT props object** — `useCreateDepositParams`, `useCreateWithdrawParams`, `useCreateSupplyLiquidityParams`, `useCreateDecreaseLiquidityParams` — NOT `{ params: { ... } }`-wrapped. The builders take **no** `srcChainKey`/`srcAddress` input — you add those (using v2's `srcChainKey`, not v1's `srcChainId`) when spreading the builder's result into the mutation's `params` field at the call site.
13
13
 
14
14
  ## Per-method delta
15
15
 
@@ -52,7 +52,7 @@ These keep their name but their TypeScript signature is different. Usually requi
52
52
  | `useRequestTrustline` | Custom utility hook (NOT a canonical mutation). Takes `(token: string \| undefined)` positionally, returns `{ requestTrustline, isLoading, isRequested, error, data }`. The `requestTrustline` callback takes `{ token, amount, srcChainKey, walletProvider }`. |
53
53
  | `useBackendOrderbook` / `useBackendAllMoneyMarketBorrowers` | Pagination MUST be nested under `params`: `{ params: { pagination: { offset, limit } } }`. |
54
54
  | `useBackendUserIntents` | Data is `UserIntentsResponse = { items: IntentResponse[], total, offset, limit }` — NOT a bare array. Access `data?.items`. |
55
- | `useBackendSubmitSwapTx` | Mutation. `apiConfig` moved from hook init to `mutate(vars)`. |
55
+ | `useSwapsApiSubmitTx` / `useSwapsApiSubmitTxStatus` (v1: `useBackendSubmitSwapTx` / `useBackendSubmitSwapTxStatus`) | Renamed + moved to the `swapsApi/` namespace (keys now `['swapsApi', …]`). Mutation `apiConfig` moved from hook init to `mutate(vars)`; the status query now requires `srcChainKey`. The rest of the Swaps API v2 is newly wrapped as `useSwapsApi*` hooks. |
56
56
  | All migration hooks | **NEW**: 6 per-action hooks replacing v1's single `useMigrate`. See [`deleted-hooks.md`](deleted-hooks.md). |
57
57
  | `useMigrationAllowance` | Query params nest under `params` with inner field literally named `params` (NOT `payload`): `{ params: { params: <migration-params>, action: 'migrate' \| 'revert' } }`. |
58
58
  | `BalnMigrateParams` (used by `useMigrateBaln`) | NEW required field `stake: boolean`. `lockupPeriod` is the `LockupPeriod` enum (5 members; values in seconds, not months). |
@@ -33,7 +33,7 @@ Granular skill for the lending/borrowing hooks of `@sodax/dapp-kit` v2. queryKey
33
33
  - **Treating `useMMAllowance` `undefined` as "not approved" for borrow/withdraw.** The query is `enabled: false` for those actions — `undefined` means "approval not required."
34
34
  - **Passing the MM params directly under `params` on `useMMAllowance`.** They nest under `params.payload`.
35
35
  - **Treating mutation `data` as `Result<T>`.** `data` is the unwrapped `TxHashPair = { srcChainTxHash, dstChainTxHash }`.
36
- - **Skipping a health-factor warning.** Render a warning when `useUserFormattedSummary().healthFactor` is near/below 1.0.
36
+ - **Skipping a health-factor warning, or comparing it wrong.** `healthFactor` is a **string**, and a no-debt position returns the sentinel `'-1'` — so `Number(hf)` it and exclude `-1` before warning: `const hf = Number(summary.healthFactor); if (hf !== -1 && hf < 1.05) { /* warn */ }`. A raw `healthFactor < 1.05` is a TS error and would also flag a debt-free user.
37
37
 
38
38
  ## Migration workflow (port v1 MM hooks to v2)
39
39
 
@@ -34,7 +34,7 @@ Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backen
34
34
  - **Passing the SDK request directly under `params` on `useQuote`.** It nests under `params.payload` (a `SolverIntentQuoteRequest`). `useSwapAllowance` nests `payload` + `srcChainKey` + `walletProvider` under `params`.
35
35
  - **Reading `data.status` on `useQuote` / `useStatus` without `data?.ok`.** Both return a `Result<…>` as their `data` — branch on `.ok` first. (`useSwapAllowance` is the opposite — already-unwrapped `boolean`.)
36
36
  - **`useStatus` key is `intentTxHash`, not `intentHash`.**
37
- - **Flattening `getSupportedSwapTokens()` and keying rows on `address`.** The same token address recurs across chains — use a composite `${address}-${blockchain_id}` key.
37
+ - **Flattening `getSupportedSwapTokens()` and keying rows on `address`.** The same token address recurs across chains — use a composite `${address}-${chainKey}` key (`XToken` carries `chainKey`, not `blockchain_id`).
38
38
  - **Reaching for `useSpokeProvider`.** Deleted. Pass `walletProvider` into `mutate(vars)` for `useSwap`/`useSwapApprove`; cancel hooks take it flat.
39
39
 
40
40
  ## Migration workflow (port v1 swap hooks to v2)
@@ -55,7 +55,7 @@ Granular skill for the swap hooks of `@sodax/dapp-kit` v2. React-only — backen
55
55
  ## Related granular skills (same family)
56
56
 
57
57
  - [`../money-market/SKILL.md`](../money-market/SKILL.md) — if the swap feeds a supply/borrow action.
58
- - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useBackendSubmitSwapTx` / intent-tracking + orderbook reads (step-by-step swap + diagnostics), partner fee-claim swaps.
58
+ - [`../auxiliary-services/SKILL.md`](../auxiliary-services/SKILL.md) — `useSwapsApiSubmitTx` / intent-tracking + orderbook reads (step-by-step swap + diagnostics), partner fee-claim swaps.
59
59
 
60
60
  For tasks spanning multiple features, load the broad [`sodax-dapp-kit` skill](../SKILL.md) instead.
61
61
 
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-sdk
3
- description: 'Integrate SODAX cross-chain DeFi into a backend, Node script, bot, indexer, or non-React app with @sodax/sdk — swaps, lending/borrowing, staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery across Sonic (hub) + 19 spoke chains. INTEGRATION (write NEW v2 code) — hub-and-spoke architecture across EVM and non-EVM chains; covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, token migration, partner fees, and stuck-asset recovery. Use whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol. For React dapps, prefer `sodax-dapp-kit` instead. MIGRATION (port v1 → v2) — the v2 reshape replaced `*SpokeProvider` classes with chain-key-driven routing, throws with `Result<T>`, module-specific error unions with `SodaxError<C>`, ad-hoc wallet/raw branching with `WalletProviderSlot<K, Raw>`, and static lookup tables with `ConfigService`. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "useSpokeProvider broken", "Sodax error types changed", v1 fingerprints (`_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError`). Load this skill if EITHER applies; the body gates by mode.'
3
+ description: 'Integrate SODAX cross-chain DeFi into a backend, Node script, bot, indexer, or non-React app with @sodax/sdk — swaps, lending/borrowing, staking, bridging, concentrated-liquidity DEX, ICX/bnUSD/BALN token migration, partner fees, and stuck-asset recovery across Sonic (hub) + 20 spoke chains. INTEGRATION (write NEW v2 code) — hub-and-spoke architecture across EVM and non-EVM chains; covers intent-based swaps, lending/borrowing (money market), staking, bridging, concentrated-liquidity DEX, token migration, partner fees, and stuck-asset recovery. Use whenever a non-React or backend codebase calls `@sodax/sdk` directly (Node scripts, indexers, bots, server APIs, custom non-React browser flows). Triggers on "use @sodax/sdk", "swap with Sodax", "Sodax bridge", "Sodax money market", "Sodax staking", "cross-chain DeFi", "Sonic hub", any `Sodax` / `ChainKeys` / `Result<T>` / `SodaxError` symbol. For React dapps, prefer `sodax-dapp-kit` instead. MIGRATION (port v1 → v2) — the v2 reshape replaced `*SpokeProvider` classes with chain-key-driven routing, throws with `Result<T>`, module-specific error unions with `SodaxError<C>`, ad-hoc wallet/raw branching with `WalletProviderSlot<K, Raw>`, and static lookup tables with `ConfigService`. Triggers on "migrate Sodax v1", "upgrade @sodax/sdk", "v1 → v2", "useSpokeProvider broken", "Sodax error types changed", v1 fingerprints (`_MAINNET_CHAIN_ID`, `*SpokeProvider`, `xChainId`, `SpokeChainId`, `MoneyMarketError`/`IntentError`/`StakingError`/`BridgeError`/`MigrationError`/`AssetServiceError`/`ConcentratedLiquidityError`/`RelayError`). Load this skill if EITHER applies; the body gates by mode.'
4
4
  license: MIT
5
5
  metadata:
6
6
  version: '0.0.1'
@@ -33,7 +33,8 @@ If the user has already picked a single feature, load the matching granular skil
33
33
  | ICX / bnUSD / BALN token migration to SODAX | [`./migration/SKILL.md`](./migration/SKILL.md) | "migrate ICX", "legacy bnUSD", "BALN lockup" (NOT v1→v2 SDK porting) |
34
34
  | Partner fees | [`./partner/SKILL.md`](./partner/SKILL.md) | "claim partner fee", "partner auto-swap preference", "approve partner fee token" |
35
35
  | Stuck-asset recovery | [`./recovery/SKILL.md`](./recovery/SKILL.md) | "recover stuck assets on Sonic", "RecoveryService", "withdrawHubAsset" |
36
- | Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "submit swap tx to backend", "getIntentByHash", "Sodax backend API", "custom IConfigApi" |
36
+ | Backend HTTP client (intents, orderbook, MM reads) | [`./backend-api/SKILL.md`](./backend-api/SKILL.md) | "getIntentByHash", "Sodax backend API", "orderbook", "custom IConfigApiV1" |
37
+ | Swaps API v2 client (quote, create-intent, submit-tx, fees) | [`./swaps-api/SKILL.md`](./swaps-api/SKILL.md) | "sodax.api.swaps", "swap quote from backend", "submit swap tx", "swaps API v2" |
37
38
 
38
39
  Load this broad skill (keep reading below) when:
39
40
 
@@ -55,7 +56,7 @@ This skill documents the **SDK call sites** — what to import, how to construct
55
56
 
56
57
  - **Multi-user state** (Telegram bot per-user wallets, dApp session storage, custodial vs non-custodial design). Hold one wallet-provider instance per user/chain at the app layer and pass it into each call — the SDK is stateless.
57
58
  - **UI**, framework wiring, route handlers, webhooks. Pick your own framework (telegraf/grammy for bots, Next.js / Vite for web, etc.) — the SDK has no opinion.
58
- - **Token discovery beyond `sodax.config`**. The SDK exposes `sodax.config.findSupportedTokenBySymbol(chainKey, symbol)` for per-chain lookups and `sodax.bridge.getBridgeableTokens(from, to, srcAddress)` / `sodax.bridge.isBridgeable({ from, to })` for vault-pair checks. There is no exhaustive "all bridgeable pairs across all chains" table — derive it at runtime if needed.
59
+ - **Token discovery beyond `sodax.config`**. The SDK exposes `sodax.config.findSupportedTokenBySymbol(chainKey, symbol)` for per-chain lookups and `sodax.bridge.getBridgeableTokens(from, to, token)` / `sodax.bridge.isBridgeable({ from, to })` for vault-pair checks. There is no exhaustive "all bridgeable pairs across all chains" table — derive it at runtime if needed.
59
60
 
60
61
  If the consumer needs a runnable end-to-end app (Node bot, CLI, full dApp), the right combination is: this skill (for SDK call sites) + `sodax-wallet-sdk-core` (for wallet providers) + the consumer's chosen framework code. The SDK does not ship an app skeleton.
61
62
 
@@ -75,7 +76,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
75
76
 
76
77
  1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
77
78
  2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
78
- 3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md`.
79
+ 3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md`, `swaps-api.md`.
79
80
  4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors, logging), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
80
81
  5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
81
82
  6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
@@ -110,7 +111,7 @@ If the consumer has v1 fingerprints AND also wants new features: **do migration
110
111
  1. Read [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions. **Read first** — prevents the most common porting mistakes.
111
112
  2. Read [`migration-v1-to-v2/knowledge/README.md`](./migration-v1-to-v2/knowledge/README.md) — overview, reading order, cross-cutting checklist, v1↔v2 glossary.
112
113
  3. **Cross-cutting first.** In order:
113
- - [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApi` Result.
114
+ - [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApiV1` Result.
114
115
  - [`breaking-changes/architecture.md`](./migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
115
116
  - [`breaking-changes/result-and-errors.md`](./migration-v1-to-v2/knowledge/breaking-changes/result-and-errors.md) — throws → `Result<T>`; module errors → `SodaxError<C>`; v1↔v2 code crosswalk.
116
117
  4. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `migration.md`, `partner.md`, `recovery.md`, `backend-api.md` — read only the ones the consumer uses.