@sodax/skills 2.1.0-rc.3 → 2.1.0-rc.5

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.
package/package.json CHANGED
@@ -4,7 +4,7 @@
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
7
- "version": "2.1.0-rc.3",
7
+ "version": "2.1.0-rc.5",
8
8
  "license": "MIT",
9
9
  "description": "AI-agent skills and knowledge for consumers of @sodax/* SDKs (Claude Code, Codex, Cursor, …)",
10
10
  "keywords": [
@@ -75,6 +75,18 @@ useSwapsApiSubmitTx({ mutationOptions }); // mutation → sodax.ap
75
75
  useSwapsApiSubmitTxStatus({ params, queryOptions }); // query → sodax.api.swaps.getSubmitTxStatus
76
76
  ```
77
77
 
78
+ These hooks forward the body verbatim, so `partnerFee` has no default (SDK fee config does not
79
+ apply). Put the same value on quote and create-intent:
80
+
81
+ ```ts
82
+ // @ai-snippets-skip
83
+ const partnerFee = { address: '0xSonicFeeReceiver', percentage: 10 }; // 10 = 0.1% (bps)
84
+ const { data: quote } = useSwapsApiQuote({ params: { body: { ...quoteBody, partnerFee } } });
85
+ await createIntent({ body: { ...intentBody, partnerFee } });
86
+ ```
87
+
88
+ See the `sodax-sdk` skill (integration mode), `swaps-api.md` § `partnerFee`.
89
+
78
90
  `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 }`):
79
91
 
80
92
  ```ts
@@ -13,6 +13,7 @@ useLeverageYieldVaultSwap({ mutationOptions }); // EXECUTE the built payload en
13
13
  useLeverageYieldNotifySolver({ mutationOptions }); // manual-flow: notify the solver after a self-driven relay
14
14
 
15
15
  // Reads
16
+ useLeverageYieldQuote({ params, queryOptions }); // vault deposit/withdraw quote (3s) — NOT useQuote
16
17
  useLeverageYieldEffectiveApr({ params, queryOptions }); // AAVE + LSD effective net APR (60s)
17
18
  useLeverageYieldPosition({ params, queryOptions }); // collateral/debt/ltv/healthFactor/idle (30s)
18
19
  useLeverageYieldTotalAssets({ params, queryOptions }); // vault TVL, 18-dp bigint (60s)
@@ -88,10 +89,11 @@ Leverage-yield has **no dedicated approve hook**. A deposit is a swap-style inte
88
89
 
89
90
  ## Return shapes
90
91
 
91
- 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`.
92
+ 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`. **`useLeverageYieldQuote` is the one exception**: it returns the SDK `Result` as `data`, matching `useQuote` on the swap side, because a quote failure ("no path", thin liquidity) is an expected UI branch and the `Result` preserves the solver's `detail.code`. Branch on `data?.ok` for that one hook only.
92
93
 
93
94
  | Hook | Returns |
94
95
  |---|---|
96
+ | `useLeverageYieldQuote` | `UseQueryResult<Result<SolverIntentQuoteResponse, SolverErrorResponse \| LeverageYieldLookupError> \| undefined, Error>` (Result **not** unwrapped; `undefined` while `payload` is undefined). Guard the error with `isSodaxError` — the `SolverErrorResponse` arm has `detail.code`, the `SodaxError` arm has `.code` (`VALIDATION_FAILED` / `LOOKUP_FAILED` / `UNKNOWN`) |
95
97
  | `useLeverageYieldDeposit` / `useLeverageYieldWithdraw` | `SafeUseMutationResult<LeverageYieldSwapPayload, Error, …>` (builder — `data` is the payload to spread into `useLeverageYieldVaultSwap`) |
96
98
  | `useLeverageYieldVaultSwap` | `SafeUseMutationResult<VaultSwapResponse, Error, …>` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
97
99
  | `useLeverageYieldNotifySolver` | `SafeUseMutationResult<SolverExecutionResponse, Error, …>` (`{ answer: 'OK', intent_hash }`) |
@@ -107,7 +109,7 @@ All read hooks here are **already unwrapped** — they throw on SDK `!ok` so `is
107
109
  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`).
108
110
  3. **The share-balance key segment is singular: `shareBalance`** (`['leverageYield', 'shareBalance', vault, chainKey, address]`) — one per holder, even though the hook name is plural.
109
111
  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.
110
- 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.
112
+ 5. **Quote vault flows with `useLeverageYieldQuote`, never `useQuote`.** `useQuote` deducts the effective *swap* fee (`swaps.partnerFee ?? fee`) while a vault intent charges the effective *leverage-yield* fee (`leverageYield.partnerFee ?? fee`) — they disagree whenever the two feature fees differ, and when the leverage-yield one is larger the `minOutputAmount` you derive is unfillable and the intent never settles. Pass the same per-intent `partnerFee` to `useLeverageYieldQuote` and to `useLeverageYieldDeposit` / `useLeverageYieldVaultSwap`, or omit it on both — either way the two sides resolve the same fee.
111
113
  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.
112
114
  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.
113
115
 
@@ -19,6 +19,7 @@ Leveraged-yield ERC-4626 vaults on Sonic. Deposit any token → `lsoda*` shares,
19
19
 
20
20
  | Hook | Purpose |
21
21
  |------|---------|
22
+ | `useLeverageYieldQuote` | Quote a deposit/withdraw with the leverage-yield fee (returns the SDK `Result` as `data`) |
22
23
  | `useSwapAllowance` | Check spoke `inputToken` approval (deposit only — swap-domain hook) |
23
24
  | `useLeverageYieldEffectiveApr` | AAVE + LSD effective net APR |
24
25
  | `useLeverageYieldPosition` | Live position (collateral, debt, LTV, health factor, idle) |
@@ -107,7 +108,7 @@ function DepositForm({ vault, srcAddress, inputToken }: { vault: Address; srcAdd
107
108
  const built = await buildDeposit({
108
109
  vault, srcChainKey: chainKey, srcAddress, inputToken,
109
110
  inputAmount: parseUnits(amount, 18),
110
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then subtract slippage
111
+ minOutputAmount: 0n, // size via useLeverageYieldQuote (token_dst = vault), then subtract slippage
111
112
  partnerFee: DEPOSIT_PARTNER_FEE, // per-intent fee — must match the quote's post-fee amount
112
113
  });
113
114
  if (!built.ok) return;
@@ -149,7 +150,7 @@ function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Add
149
150
  vault, srcChainKey: chainKey, srcAddress,
150
151
  dstChainKey: chainKey, outputToken,
151
152
  inputAmount: shares, // lsoda* shares to burn
152
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault), then subtract slippage
153
+ minOutputAmount: 0n, // size via useLeverageYieldQuote (token_src = vault), then subtract slippage
153
154
  });
154
155
  if (!built.ok) return;
155
156
  await vaultSwap({ ...built.value, walletProvider }); // built.value.hubWalletSwap === true
@@ -162,7 +163,8 @@ function WithdrawButton({ vault, srcAddress, outputToken, shares }: { vault: Add
162
163
  ## Notes
163
164
 
164
165
  - **Two roles:** `deposit` / `withdraw` *build* a `LeverageYieldSwapPayload`; `useLeverageYieldVaultSwap` *executes* it. Always spread the built payload into the executor with a `walletProvider`.
165
- - **Quotes:** size `minOutputAmount` with `sodax.swaps.getQuote` — vault address as `token_dst` (deposit) or `token_src` (withdraw), since `lsoda*` shares are solver-tradeable. Subtract your slippage tolerance.
166
- - **Deposit fee:** a per-intent `partnerFee` is deducted from `inputAmount` before the swap; quote on the post-fee amount or the intent won't fill.
166
+ - **Quotes:** size `minOutputAmount` with `useLeverageYieldQuote` — vault address as `token_dst` (deposit) or `token_src` (withdraw). Not `useQuote`: that one deducts the effective *swap* fee, while the vault intent charges the effective *leverage-yield* fee, so the quote and the intent disagree whenever the two feature fees differ. It returns the SDK `Result` as `data` (branch on `data?.ok`), unlike the other leverage-yield read hooks. Subtract your slippage tolerance.
167
+ - **Fees apply BOTH ways.** Deposits *and* withdrawals are charged the effective leverage-yield fee (`leverageYield.partnerFee ?? fee`); both builders accept an optional `partnerFee` to override it per intent. The fee comes out of `inputAmount` before the swap, so pass the same `partnerFee` to `useLeverageYieldQuote` or the quote is sized on the wrong net input and the intent won't fill. On a withdraw the input token is the vault, so the fee is taken in **`lsoda*` shares** — the receiver accrues vault shares, not the output token.
168
+ - **Configured fee:** vault flows are monetized via `leverageYield.partnerFee` (else the global `fee`). `swaps.partnerFee` does not apply to them.
167
169
  - **Withdraw:** no spoke approval — the hub wallet authorises the share spend via `Connection.sendMessage`. Output lands at `recipient` (defaults to `srcAddress`) on `dstChainKey`.
168
170
  - **Reads** (`useLeverageYieldEffectiveApr`, `Position`, `TotalAssets`, `PreviewRedeem`) are already unwrapped — read `data` directly. `useLeverageYieldShareBalances` returns an array; aggregate the `shares` yourself.
@@ -204,6 +204,7 @@ Typed wrappers over `sodax.api.bridge.*` (one per Bridge API v2 endpoint), all k
204
204
 
205
205
  | Key | Hook |
206
206
  |---|---|
207
+ | `['leverageYield', 'quote', payload]` | `useLeverageYieldQuote` (payload object with `amount` and any `partnerFee.amount` stringified — React Query hashes keys with `JSON.stringify`, which throws on bigint) |
207
208
  | `['leverageYield', 'effectiveApr', vault]` | `useLeverageYieldEffectiveApr` |
208
209
  | `['leverageYield', 'position', vault]` | `useLeverageYieldPosition` |
209
210
  | `['leverageYield', 'totalAssets', vault]` | `useLeverageYieldTotalAssets` |
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: sodax-sdk-bridge-api
3
- description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API v2 (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "bridge API v2", "point bridge at a custom endpoint", "bridgeOptions.useBackendSubmitTx"). For the higher-level end-to-end bridge orchestrator use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
3
+ description: 'Granular skill for the @sodax/sdk v2 Bridge API client — `sodax.api.bridge` (class BridgeApiService), a typed HTTP client for the backend Bridge API v2 (`/bridge/*`: tokens, allowance/approve, create-bridge-intent, submit-tx + status, fee/bridgeable-amount/bridgeable discovery). Every method returns Promise<Result<T>>, never throws, and validates the response. Use when the task calls the bridge backend directly (e.g. "sodax.api.bridge", "createBridgeIntent via the backend API", "submit bridge tx", "poll bridge submit-tx status", "bridge API v2", "point bridge at a custom endpoint", "bridge.useBackendSubmitTx"). For the higher-level end-to-end bridge orchestrator use the `bridge` skill instead. Skill links into the parent sodax-sdk knowledge tree.'
4
4
  ---
5
5
 
6
6
  # Bridge API (Core SDK granular skill)
@@ -25,7 +25,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
25
25
  ## Integration workflow
26
26
 
27
27
  1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md) — DO / DO NOT (read first).
28
- 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridgeOptions.useBackendSubmitTx`.
28
+ 2. [`../integration/knowledge/features/bridge-api.md`](../integration/knowledge/features/bridge-api.md) — the full client: signatures, deltas vs swaps (no intent, FULL relayData envelope, 5-state tolerant status), common call shapes (create-intent, submit-tx + status), the read-only fee/bridgeable-amount/bridgeable discovery quotes, per-call overrides, `bridge.useBackendSubmitTx`.
29
29
  3. For the end-to-end bridge flow that wraps these calls → [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md); for the sibling swaps client → [`../integration/knowledge/features/swaps-api.md`](../integration/knowledge/features/swaps-api.md); for the read client (`sodax.backendApi`) → [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md).
30
30
  4. Errors are `Result<T, SodaxError<'EXTERNAL_API_ERROR'>>` → [`../integration/knowledge/recipes/result-and-errors.md`](../integration/knowledge/recipes/result-and-errors.md) and [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
31
31
 
@@ -42,10 +42,10 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'bridge
42
42
  ## Migration workflow (on-chain → API)
43
43
 
44
44
  There is **no v1 Bridge API** — the typed `sodax.api.bridge` client is v2-new. The relevant move is from the
45
- on-chain `sodax.bridge.bridge()` orchestrator to the API client (or to the orchestrator's opt-in backend
46
- path via `bridgeOptions.useBackendSubmitTx`):
45
+ on-chain `sodax.bridge.bridge()` orchestrator to the API client (or to the orchestrator's default-on backend
46
+ path via `bridge.useBackendSubmitTx`):
47
47
 
48
- 1. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — the on-chain `BridgeService` orchestrator and the `bridgeOptions.useBackendSubmitTx` toggle that routes its spoke-deposit through this API with a client-side fallback.
48
+ 1. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — the on-chain `BridgeService` orchestrator and the `bridge.useBackendSubmitTx` toggle that routes its spoke-deposit through this API with a client-side fallback.
49
49
  2. For the v1 → v2 reshape of the on-chain bridge itself (chain-key routing, `Result<T>`, error unions) → [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md).
50
50
 
51
51
  ## Verification
@@ -163,7 +163,7 @@ new Sodax(config?: SodaxOptions): Sodax;
163
163
  - `dex: DexConfig` — DEX pool/asset config.
164
164
  - `leverageYield: LeverageYieldConfig` — registry of leverage-yield ERC-4626 vaults on the hub.
165
165
  - `hub: HubConfig` — hub-chain (Sonic) full address map + RPC URL + polling config. Accepts an optional `rpcUrls` failover list (and `rpcOptions` tuning) — see [`recipes/initialize-sodax.md`](recipes/initialize-sodax.md).
166
- - `api: ApiConfig` — backend API config: flat `BaseApiConfig` (`{ baseURL, timeout, headers }`, shared by `sodax.backendApi` and the swaps client `sodax.api.swaps`) or nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint.
166
+ - `api: ApiConfig` — backend API config: flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`, shared by `sodax.backendApi` and the swaps client `sodax.api.swaps`) or nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. `baseURL` is the gateway root; each service appends its own path below it.
167
167
  - `solver: SolverConfig` — `{ intentsContract, solverApiEndpoint, protocolIntentsContract }`.
168
168
  - `relay: RelayConfig` — intent relay endpoint + chain-id map.
169
169
 
@@ -202,15 +202,16 @@ Chain configs (vault addresses, supported tokens, fee parameters) change between
202
202
 
203
203
  ### Custom backend
204
204
 
205
- Point at a custom backend URL via `SodaxConfig.api.baseURL`:
205
+ Point at a custom backend URL via `SodaxConfig.api`. `baseURL` is the gateway root; the data API's `/be`
206
+ mount is appended below it, so a sandbox serving `/config/*` at its bare origin needs `basePath: ''`:
206
207
 
207
208
  ```ts
208
209
  const sodax = new Sodax({
209
- api: { baseURL: 'https://sandbox-api.example.com' },
210
+ api: { baseApiConfig: { baseURL: 'https://sandbox-api.example.com', basePath: '' } },
210
211
  });
211
212
  ```
212
213
 
213
- `SodaxConfig.api` is `ApiConfig` — the flat `BaseApiConfig` (`{ baseURL, timeout, headers }`) shared by both backend clients, or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API (`sodax.api.swaps`) at its own endpoint. Pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApiV1` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server, or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
214
+ `SodaxConfig.api` is `ApiConfig` — the flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`) shared by both backend clients, or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API (`sodax.api.swaps`) at its own endpoint. `baseURL` is the gateway root and every service appends its own path below it (`/be`, `/swaps`, `/bridge`, `/sponsorships/stellar`), so it must never carry a service segment; `basePath` overrides the data API's mount for a non-gateway deployment. Pass any subset via `DeepPartial`. v2 does not provide a typed slot to inject a custom `IConfigApiV1` implementation at construction; if you need to mock the backend for tests, point `baseURL` at a local mock server (with `basePath: ''` when it serves the routes at its origin), or construct your own `BackendApiService`-compatible mock and inject it where you control the `Sodax` instance (e.g. dependency-injected in your app layer).
214
215
 
215
216
  ---
216
217
 
@@ -64,7 +64,7 @@ source token rejects a non-zero to non-zero allowance change (Ethereum USDT is t
64
64
  today) **and** the wallet already holds a stale allowance — broadcast it first, wait for it to be
65
65
  mined, then broadcast `tx`. Absent for every other token, so a client that ignores it keeps working.
66
66
 
67
- `CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
67
+ `CreateIntentParamsV2` is the shared wire-level request body behind the typed `/swaps/allowance/check`, `/swaps/approve`, and `/swaps/intents` calls (the `IBackendApiV2` methods the SDK drives internally). It inherits the swap extras — `partnerFee`, `srcPublicKey`, and `bound` — from `SwapExtrasV2`, the JSON-safe mirror of the SDK `SwapExtras` (`QuoteRequestV2` inherits the same trio for its `includeTxData=true` path). `partnerFee` has no default on this path — see [`swaps-api.md`](swaps-api.md) § `partnerFee`. For Bitcoin **TRADING**-mode `raw` intents the Bound Exchange (Radfi) token is carried as `bound.accessToken` — passed in the request body instead of an `x-bound-access-token` header so it stays inside the typed DTO. Required only when the source chain is Bitcoin in TRADING mode; ignored otherwise.
68
68
 
69
69
  You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token via the chain-key-gated `extras.bound.accessToken` slot and maps it onto `CreateIntentParamsV2.bound.accessToken`. See [`swap.md`](swap.md) § `SwapExtras` and [`../chain-specifics.md`](../chain-specifics.md) § "Bitcoin PSBT and Bound Exchange" for the consumer-facing flow and token-injection points.
70
70
 
@@ -76,12 +76,16 @@ You rarely build this DTO yourself: `sodax.swaps.createIntent` takes the token v
76
76
 
77
77
  ```ts
78
78
  const sodax = new Sodax({
79
- api: { baseURL: 'http://localhost:4000' },
79
+ // `basePath: ''` because a local mock serves `/config/*` at its origin, with no `/be` mount.
80
+ api: { baseApiConfig: { baseURL: 'http://localhost:4000', basePath: '' } },
80
81
  });
81
82
  await sodax.config.initialize();
83
+ // → http://localhost:4000/config/all
82
84
  ```
83
85
 
84
- `SodaxConfig.api` is `ApiConfig` — either the flat `BaseApiConfig` (`{ baseURL, timeout, headers }`, shared by the base API and the swaps client) or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. Pass any subset via `DeepPartial`. See [`./swaps-api.md`](swaps-api.md) § "Custom endpoint for the swaps API".
86
+ `SodaxConfig.api` is `ApiConfig` — either the flat `BackendApiConfig` (`{ baseURL, basePath?, timeout, headers }`, shared by the base API and the swaps client) or the nested `CustomApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) to point the swaps API at its own endpoint. Pass any subset via `DeepPartial`. See [`./swaps-api.md`](swaps-api.md) § "Custom endpoint for the swaps API".
87
+
88
+ `baseURL` is the **gateway root** — each service appends its own path below it, so the backend data API requests `<baseURL>/be/config/all` by default. `basePath` is that mount, and the only reason to set it is a deployment that does not use the gateway. Never put a service segment (`/be`, `/swaps`, `/bridge`) in `baseURL` itself — it would also relocate the sibling services. A `baseURL` ending in `/be` is trimmed with a deprecation warning; do not rely on that.
85
89
 
86
90
  2. **Inject your own `BackendApiService`-compatible mock at the app layer** (dependency-injected where you control the `Sodax` instance), rather than via the constructor.
87
91
 
@@ -108,19 +108,21 @@ if (status.ok && status.value.data.status === 'executed') {
108
108
  Every method accepts a trailing `RequestOverrideConfig` to redirect a single call or attach headers:
109
109
 
110
110
  ```ts
111
- await sodax.api.bridge.getTokens({ baseURL: 'https://staging.example/v1/be', headers: { 'X-Trace': 'abc' } });
111
+ // `baseURL` is the gateway ROOT — the SDK appends `/bridge/*` itself. Never include a service segment.
112
+ await sodax.api.bridge.getTokens({ baseURL: 'https://staging.example/v1', headers: { 'X-Trace': 'abc' } });
112
113
  ```
113
114
 
114
- The Bridge API has no dedicated config slice — it always shares the base backend host (`/bridge/*`). To
115
+ The Bridge API has no dedicated config slice — it always shares the base backend host, reached as
116
+ `/bridge/*` on the gateway root (a sibling of the data API's `/be` mount, not a child of it). To
115
117
  move the whole backend (including bridge) to a custom host, use the `CustomApiConfig` `baseApiConfig` slice
116
118
  (see [`backend-api.md`](backend-api.md) § "Custom backend").
117
119
 
118
- ## Orchestrator integration — `bridgeOptions.useBackendSubmitTx`
120
+ ## Orchestrator integration — `bridge.useBackendSubmitTx`
119
121
 
120
- `new Sodax({ bridgeOptions: { useBackendSubmitTx: true } })` opts the end-to-end `sodax.bridge.bridge()`
121
- into routing the spoke-deposit through this API (`submit-tx` + status poll) with an automatic fall back to
122
- the client-side relay on any non-success. **Default OFF.** This is a distinct key from
123
- `swapsOptions.useBackendSubmitTx`. See [`bridge.md`](bridge.md) and the `CONFIGURE_SDK` doc.
122
+ `bridge.useBackendSubmitTx` (default `true`) routes the end-to-end `sodax.bridge.bridge()` through this
123
+ API (`submit-tx` + status poll) with an automatic fall back to the client-side relay on any non-success.
124
+ Set `new Sodax({ bridge: { useBackendSubmitTx: false } })` to force the client-side path. Independent of
125
+ `swaps.useBackendSubmitTx`. See [`bridge.md`](bridge.md) and the `CONFIGURE_SDK` doc.
124
126
 
125
127
  ## Error handling
126
128
 
@@ -33,7 +33,7 @@ type BridgeParams<K extends SpokeChainKey, Raw extends boolean> = {
33
33
  params: CreateBridgeIntentParams<K>;
34
34
  extras?: BridgeExtras<K>;
35
35
  skipSimulation?: boolean;
36
- timeout?: number; // shared budget for relay/poll; defaults to DEFAULT_RELAY_TX_TIMEOUT
36
+ timeout?: number; // per-attempt budget (backend attempt, then fallback relay); defaults to DEFAULT_RELAY_TX_TIMEOUT
37
37
  } & WalletProviderSlot<K, Raw>; // raw: true ⇒ no walletProvider; raw: false ⇒ required, chain-narrowed
38
38
 
39
39
  type CreateBridgeIntentParams<K extends SpokeChainKey> = {
@@ -83,7 +83,7 @@ const result = await sodax.bridge.bridge({
83
83
 
84
84
  ## Routing the spoke deposit through the backend
85
85
 
86
- `bridge()` relays client-side by default. `new Sodax({ bridgeOptions: { useBackendSubmitTx: true } })` opts into handing the broadcast deposit to the backend Bridge API instead (`sodax.api.bridge`), which relays server-side and falls back to the client-side relay on any non-success — safe because re-relaying is idempotent. Default is OFF. See [`bridge-api.md`](bridge-api.md).
86
+ `bridge()` routes the spoke-deposit through the backend Bridge API by default (`bridge.useBackendSubmitTx`, default ON) — `sodax.api.bridge` relays server-side and falls back to the client-side relay on any non-success — safe because re-relaying is idempotent. Set `new Sodax({ bridge: { useBackendSubmitTx: false } })` to force the client-side path. As with swaps, the SDK does not verify the deposit on-chain before handing it over — the backend verifies itself, so `verifyTxHash` runs on the client-side path only. `timeout` (defaults to `DEFAULT_RELAY_TX_TIMEOUT`) is a PER-ATTEMPT budget, same terms as swaps: the backend attempt gets it and the fallback relay gets a fresh one starting after verification, so neither a stalled backend nor a slow confirmation shortens the fallback. Worst case is `createBridgeIntent + timeout + verification + max(timeout, RELAY_FALLBACK_FLOOR_MS)` — intent creation and verification (the source chain's `pollingConfig.maxTimeoutMs`) are not bounded by `timeout`. Bridge has no post-execution term. See [`bridge-api.md`](bridge-api.md).
87
87
 
88
88
  ## Common call shapes
89
89
 
@@ -14,6 +14,11 @@ Access: `sodax.leverageYield`. Service class: `LeverageYieldService`. Feature ta
14
14
  ## Public methods
15
15
 
16
16
  ```ts
17
+ // Quote — solver quote sized with the effective leverage-yield fee (NOT sodax.swaps.getQuote)
18
+ sodax.leverageYield.getQuote(payload: LeverageYieldQuoteParams): Promise<Result<SolverIntentQuoteResponse, SolverErrorResponse | LeverageYieldLookupError>>;
19
+ // token_dst = vault to quote a deposit, token_src = vault to quote a withdraw
20
+ // pass the same partnerFee here and to deposit()/withdraw()/vaultSwap(), or omit on all — never mix
21
+
17
22
  // Builders — assemble a LeverageYieldSwapPayload (spread into vaultSwap). Do NOT broadcast.
18
23
  sodax.leverageYield.deposit(params: LeverageYieldSwapDepositParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
19
24
  sodax.leverageYield.withdraw(params: LeverageYieldSwapWithdrawParams): Promise<Result<LeverageYieldSwapPayload, SodaxError>>;
@@ -76,13 +81,14 @@ type LeverageYieldSwapWithdrawParams = {
76
81
  recipient?: string; // defaults to srcAddress
77
82
  deadline?: bigint;
78
83
  solver?: Address;
84
+ partnerFee?: PartnerFee; // per-intent override; deducted from inputAmount, i.e. in lsoda* shares
79
85
  };
80
86
 
81
87
  // The execute-mode wrapper (createVaultIntent / vaultSwap). The two vault execution modifiers
82
88
  // live HERE, never on the generic swap surface:
83
89
  type VaultSwapActionParams<K, Raw> = SpokeExecActionParams<K, Raw, CreateIntentParams<K>> & {
84
90
  hubWalletSwap?: boolean; // withdraw: inputToken is hub-wallet lsoda*, authorise via Connection.sendMessage
85
- partnerFee?: PartnerFee; // beats config.swaps.partnerFee for this intent only
91
+ partnerFee?: PartnerFee; // beats config.leverageYield.partnerFee for this intent only
86
92
  };
87
93
  ```
88
94
 
@@ -97,7 +103,7 @@ const built = await sodax.leverageYield.deposit({
97
103
  srcAddress: '0x…',
98
104
  inputToken: '0x…weETHonArbitrum',
99
105
  inputAmount: parseUnits('1', 18),
100
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_dst = vault), then apply slippage
106
+ minOutputAmount: 0n, // quote via sodax.leverageYield.getQuote (token_dst = vault), then apply slippage
101
107
  partnerFee: { address: '0x…', percentage: 100 }, // optional 1% per-intent fee
102
108
  });
103
109
  if (!built.ok) return;
@@ -117,7 +123,7 @@ const built = await sodax.leverageYield.withdraw({
117
123
  dstChainKey: ChainKeys.ARBITRUM_MAINNET, // token delivered here
118
124
  outputToken: '0x…weETHonArbitrum',
119
125
  inputAmount: shareBalance, // lsoda* to burn
120
- minOutputAmount: 0n, // quote via sodax.swaps.getQuote (token_src = vault)
126
+ minOutputAmount: 0n, // quote via sodax.leverageYield.getQuote (token_src = vault)
121
127
  });
122
128
  if (!built.ok) return;
123
129
  // built.value.hubWalletSwap === true — no spoke approval; the hub wallet authorises the spend
@@ -138,6 +144,7 @@ await sodax.leverageYield.notifySolver({ intent_tx_hash: hubIntentTxHash });
138
144
 
139
145
  | Method | Success type |
140
146
  |---|---|
147
+ | `getQuote` | `SolverIntentQuoteResponse` (`{ quoted_amount }`) — error is `SolverErrorResponse \| LeverageYieldLookupError`, so discriminate with `isSodaxError(error)` before reading `.code` |
141
148
  | `deposit`, `withdraw` | `LeverageYieldSwapPayload` (`{ params: CreateIntentParams; hubWalletSwap?: true; partnerFee? }`) |
142
149
  | `createVaultIntent` | `CreateVaultIntentResult<K, Raw>` (`{ tx, intent & feeAmount, relayData }`) |
143
150
  | `vaultSwap` | `VaultSwapResponse` (`{ solverExecutionResponse, intent, intentDeliveryInfo }`) |
@@ -164,6 +171,7 @@ approval can take two transactions" in [`architecture.md`](../architecture.md).
164
171
 
165
172
  | Method | Narrow code union |
166
173
  |---|---|
174
+ | `getQuote` | `VALIDATION_FAILED` (non-positive `amount`, or a partner fee that leaves nothing to quote) `\| LOOKUP_FAILED` (unsupported token — solver payload could not be assembled) `\| UNKNOWN`, **or** a non-SodaxError `SolverErrorResponse` (`{ detail: { code, message } }`) straight from the solver. Guard with `isSodaxError(error)`. Context uses `tokenSrcChainKey` / `tokenDstChainKey`, not `srcChainKey` / `dstChainKey` — a withdraw quote's `token_src` is the hub, not the signing chain |
167
175
  | `deposit`, `withdraw` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| LOOKUP_FAILED \| UNKNOWN` (create-intent subset + `LOOKUP_FAILED` with `method: 'resolveDeadline'` when the default-deadline hub-block read fails) |
168
176
  | `createVaultIntent` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| UNKNOWN` (create-intent subset) |
169
177
  | `vaultSwap` | `VALIDATION_FAILED \| INTENT_CREATION_FAILED \| TX_VERIFICATION_FAILED \| TX_SUBMIT_FAILED \| RELAY_TIMEOUT \| RELAY_FAILED \| EXECUTION_FAILED \| EXTERNAL_API_ERROR \| UNKNOWN` |
@@ -13,7 +13,7 @@ Access: `sodax.swaps`. Service class: `SwapService`. Feature tag for errors: `'s
13
13
 
14
14
  Two execution paths:
15
15
 
16
- - **`swap`** — full flow in one call. Wraps `createIntent` + relay + `postExecution`. Returns `SwapResponse` on success. Opt into a **backend-driven 2-step** variant (the backend relays + post-executes server-side) with `new Sodax({ swapsOptions: { useBackendSubmitTx: true } })`; on any non-success it falls back to the client-side relay, returning the same `SwapResponse`.
16
+ - **`swap`** — full flow in one call. Wraps `createIntent` + relay + `postExecution`. Returns `SwapResponse` on success. By default uses a **backend-driven 2-step** variant (`swaps.useBackendSubmitTx`, default `true` — the backend relays + post-executes server-side); on any non-success it falls back to the client-side relay, returning the same `SwapResponse`. Set `new Sodax({ swaps: { useBackendSubmitTx: false } })` to force client-side only. The SDK does NOT verify the tx on-chain before handing it to the backend — the backend verifies itself, so `verifyTxHash` (and `TX_VERIFICATION_FAILED`) belong to the client-side path only. `timeout` (defaults to `DEFAULT_RELAY_TX_TIMEOUT`) is a PER-ATTEMPT budget, not end-to-end: the backend attempt (submit POST + status poll) gets it, and if that attempt does not complete the client-side relay wait gets a fresh one starting after verification — so neither a stalled backend nor a slow source-chain confirmation shortens the fallback, and raising `timeout` grows both. Each backend request is clamped to `min(budget left in the attempt, api.timeout)`; `api.timeout` is configurable (packaged default `DEFAULT_BACKEND_API_TIMEOUT`), and once the attempt's remainder drops below it a single stalled request can spend what is left — the clamp bounds a request by the attempt, it does not guarantee a retry. Worst case is `createIntent + timeout + verification + max(timeout, RELAY_FALLBACK_FLOOR_MS) + postExecution`; verification is bounded by the source chain's `pollingConfig.maxTimeoutMs` (varies widely — Stacks is several times Sui — read `chains.ts`, and it is a no-op on EVM), and intent creation and post-execution are not bounded by `timeout` at all.
17
17
  - **`createIntent` + backend submit** — break it apart for custom relay handling. `createIntent` returns `{ tx, intent, relayData }`; submit `relayData.payload` to the backend swap-tx endpoint via `sodax.api.swaps.submitTx`.
18
18
 
19
19
  ## Public methods
@@ -89,15 +89,26 @@ client serializes them to decimal strings on the wire. Server-returned intents (
89
89
  back with those fields as decimal **`string`** (outbound JSON can't carry bigint). The `amount` /
90
90
  `inputAmount` fields on the quote / create-intent request bodies are already decimal **strings**.
91
91
 
92
+ ## `partnerFee`
93
+
94
+ Optional on the type, but no default: the backend does not fill it in, and
95
+ `new Sodax({ fee })` / `new Sodax({ swaps: { partnerFee } })` only reach the
96
+ `sodax.swaps` orchestrator — not this wire path. Send the same value on quote and
97
+ create-intent. `checkAllowance` / `approve` inherit the field but ignore it.
98
+ Bridge API v2 is different: omitted `partnerFee` falls back to `bridgePartnerFee`.
99
+
92
100
  ## Common call shapes
93
101
 
94
102
  ### Quote
95
103
 
96
104
  ```ts
105
+ const partnerFee = { address: '0xSonicFeeReceiver', percentage: 10 }; // 10 = 0.1% (bps)
106
+
97
107
  const quote = await sodax.api.swaps.getQuote({
98
108
  tokenSrc, tokenSrcChainKey, tokenDst, tokenDstChainKey,
99
109
  amount: '1000000', // smallest unit, decimal string
100
110
  quoteType: 'exact_input',
111
+ partnerFee,
101
112
  });
102
113
  if (!quote.ok) return;
103
114
  quote.value.quotedAmount; // decimal string
@@ -114,6 +125,7 @@ const created = await sodax.api.swaps.createIntent({
114
125
  deadline: '0', // "0" → no expiry (limit-order semantics)
115
126
  allowPartialFill: false,
116
127
  srcAddress, dstAddress,
128
+ partnerFee,
117
129
  });
118
130
  if (!created.ok) return;
119
131
  const { tx, intent, relayData } = created.value;
@@ -151,20 +163,24 @@ Every method accepts a trailing `RequestOverrideConfig` to redirect a single cal
151
163
  attach request-specific headers (auth, tracing), overriding the service config:
152
164
 
153
165
  ```ts
154
- await sodax.api.swaps.getTokens({ baseURL: 'https://staging.example/v1/be', headers: { 'X-Trace': 'abc' } });
166
+ // `baseURL` is the gateway ROOT — the SDK appends `/swaps/*` itself. Never include a service segment.
167
+ await sodax.api.swaps.getTokens({ baseURL: 'https://staging.example/v1', headers: { 'X-Trace': 'abc' } });
155
168
  ```
156
169
 
157
170
  ## Custom endpoint for the swaps API
158
171
 
159
- By default the swaps endpoints are `/swaps/*` sub-paths under the same base URL as `sodax.backendApi`.
172
+ `baseURL` is the gateway root, shared by every service; the swaps client appends `/swaps/*` below it just
173
+ as `sodax.backendApi` appends its own `/be` mount. Never put a service segment in `baseURL` — a value
174
+ ending in `/be` resolves swaps to `/v1/be/swaps/submit-tx`, which the gateway does not route (the SDK
175
+ trims that suffix, but do not rely on it).
160
176
  To point the swaps API at its own host (separate from the base backend API), construct `Sodax` with the
161
177
  **`CustomApiConfig`** variant of `ApiConfig` (`{ baseApiConfig?, swapsApiConfig? }`) instead of the flat
162
- `BaseApiConfig`:
178
+ `BackendApiConfig`:
163
179
 
164
180
  ```ts
165
181
  const sodax = new Sodax({
166
182
  api: {
167
- baseApiConfig: { baseURL: 'https://api.example/v1/be' },
183
+ baseApiConfig: { baseURL: 'https://api.example/v1' },
168
184
  swapsApiConfig: { baseURL: 'https://swaps.example/v1' },
169
185
  },
170
186
  });
@@ -18,16 +18,19 @@ const result = sodax.config.isValidSpokeChainKey(ChainKeys.ARBITRUM_MAINNET);
18
18
  import { Sodax, ChainKeys, type SodaxOptions } from '@sodax/sdk';
19
19
 
20
20
  // `SodaxOptions` = `DeepPartial<SodaxDefaultConfig>` (the data override) plus the client-side options:
21
- // `logger`, the global `fee`, and `swapsOptions` (e.g. `{ useBackendSubmitTx: true }` — opt swap() into the backend 2-step flow).
21
+ // `logger`, the global `fee`, and per-feature options on `swaps` / `bridge` (e.g. `{ useBackendSubmitTx: false }` — opt out of the default-on backend 2-step flow).
22
22
  const config: SodaxOptions = {
23
23
  // Per-chain overrides — merged with packaged defaults at the field level.
24
24
  chains: {
25
25
  [ChainKeys.SONIC_MAINNET]: { rpcUrl: process.env.SONIC_RPC_URL },
26
26
  [ChainKeys.ARBITRUM_MAINNET]: { rpcUrl: process.env.ARBITRUM_RPC_URL },
27
27
  },
28
- // Backend API override (default: https://api.sodax.com/v1/be).
28
+ // Backend API override. `baseURL` is the gateway ROOT (default: https://api.sodax.com/v1); each
29
+ // service appends its own path below it (`/be`, `/swaps`, `/bridge`, `/sponsorships/stellar`).
30
+ // A sandbox that serves `/config/*` at its bare origin has no `/be` mount, so say so with
31
+ // `basePath: ''` — otherwise the data API requests `<origin>/be/config/all`.
29
32
  api: {
30
- baseURL: 'https://my-sandbox-backend.example.com',
33
+ baseApiConfig: { baseURL: 'https://my-sandbox-backend.example.com', basePath: '' },
31
34
  },
32
35
  // Solver endpoints (default: https://api.sodax.com/v1/intent + production contracts).
33
36
  solver: {
@@ -75,13 +75,15 @@ if (!result.ok) {
75
75
 
76
76
  ### Point tests at a sandbox backend
77
77
 
78
- There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BaseApiConfig | CustomApiConfig`: pass a flat `{ baseURL, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To run tests against a sandbox or local mock server, set `api.baseURL` and let `initialize()` fetch config from it:
78
+ There is no constructor slot to inject a custom `IConfigApiV1` — the only backend knob is `api` (`ApiConfig = BackendApiConfig | CustomApiConfig`: pass a flat `{ baseURL, basePath?, timeout?, headers? }`, or a `CustomApiConfig` with separate `baseApiConfig` / `swapsApiConfig` endpoints). To run tests against a sandbox or local mock server, set `api.baseURL` and let `initialize()` fetch config from it:
79
79
 
80
80
  ```ts
81
81
  import { Sodax } from '@sodax/sdk';
82
82
 
83
83
  const sodax = new Sodax({
84
- api: { baseURL: 'https://sandbox-api.example.com' },
84
+ // `baseURL` is the gateway root; the data API's `/be` mount is appended below it. A mock that
85
+ // serves `/config/*` at its origin needs `basePath: ''`.
86
+ api: { baseApiConfig: { baseURL: 'https://sandbox-api.example.com', basePath: '' } },
85
87
  });
86
88
  await sodax.config.initialize();
87
89
  ```
@@ -138,11 +138,14 @@ import {
138
138
  type IntentRelayChainId,
139
139
 
140
140
  // Backend API config + per-call override
141
- type ApiConfig, // BaseApiConfig | CustomApiConfig
142
- type BaseApiConfig,
141
+ type ApiConfig, // BackendApiConfig | CustomApiConfig
142
+ type BaseApiConfig, // { baseURL, timeout, headers } — baseURL is the GATEWAY ROOT
143
+ type BackendApiConfig, // BaseApiConfig & { basePath? } — the data API's mount, default '/be'
143
144
  type CustomApiConfig, // point the swaps / sponsoring API at its own endpoint
144
145
  type SwapsApiConfig,
145
146
  type SponsoringApiConfig, // BaseApiConfig & { apiKey? } — own host, own x-api-key
147
+ DEFAULT_API_BASE_URL, // 'https://api.sodax.com/v1' — the root every service resolves
148
+ BACKEND_API_BASE_PATH, // '/be'
146
149
  DEFAULT_SPONSORING_API_ENDPOINT,
147
150
  SPONSORING_API_STELLAR_BASE_PATH,
148
151
  type RequestOverrideConfig, // per-call override on any backendApi / sodax.api.swaps method
@@ -33,7 +33,9 @@ Granular skill for `LeverageYieldService` — `sodax.leverageYield`. Feature tag
33
33
  - **Using `getApr` as the headline number.** For LSD-backed vaults the AAVE-only spread is often negative; `getEffectiveApr` folds in the LSD staking yield (the real source of return).
34
34
  - **Passing a spoke address to `getShareBalance` / `getMaxWithdraw`.** Those take a hub address. Use the `*ForUser(vault, srcChainKey, srcAddress)` variants to resolve the hub wallet first.
35
35
  - **Gating withdraw on `approve` / `isAllowanceValid`.** Those are Sonic-direct allowance helpers for the vault's underlying asset; the swap-style withdraw authorises the share spend via a hub-wallet `Connection.sendMessage` (`hubWalletSwap: true`).
36
- - **Quoting on the pre-fee amount.** A deposit's per-intent `partnerFee` is deducted from `inputAmount` before the swap — quote (via the swap solver, `token_dst` = vault) on the post-fee amount.
36
+ - **Quoting a vault flow through `sodax.swaps.getQuote`.** It deducts the effective *swap* fee, while the vault intent charges the effective *leverage-yield* fee (`leverageYield.partnerFee ?? fee`) — the two disagree whenever the feature fees differ. It can be made to agree by passing the leverage-yield fee explicitly (with a zero fee — `{ address, percentage: 0 }` — where that fee is `undefined`, since an explicit `undefined` falls back to the swap fee), but prefer `sodax.leverageYield.getQuote` (`token_dst` = vault for a deposit, `token_src` = vault for a withdraw).
37
+ - **Quoting with a different `partnerFee` than the intent charges.** The fee is deducted from the input before the swap, so the quote is sized on a different net input; when the intent's fee is the larger one, the `minOutputAmount` derived from that quote can't be met and the intent never fills. Pass the same `partnerFee` to `getQuote` and to `deposit()` / `vaultSwap()`, or omit it on both.
38
+ - **Assuming `swaps.partnerFee` monetizes vault flows.** It does not — configure `leverageYield.partnerFee` (or the global `fee`).
37
39
 
38
40
  ## Verification
39
41
 
@@ -32,6 +32,7 @@ validates the response. Errors carry `feature: 'backend'`, `context.api: 'swaps'
32
32
 
33
33
  ### Swaps-API-specific anti-patterns
34
34
 
35
+ - **Omitting `partnerFee` on `getQuote` / `createIntent`.** Optional on the type only — no backend/SDK default. Ask for a real fee receiver; never invent one or use the zero address.
35
36
  - **`try/catch` for failures.** Every method returns `Result<T>` — branch on `result.ok`. `catch` won't fire for HTTP/timeout/validation failures.
36
37
  - **Passing the `RelayExtraData` object** to `submitTx`'s `relayData`. The field is a `string` — pass `relayData.payload`.
37
38
  - **Stringifying `intent` numerics yourself.** `IntentRequestV2` fields are `bigint`; the client serializes them to decimal strings — pass the bigint intent through as-is.
@@ -52,7 +53,8 @@ builds on are covered in the existing swap + backend-api migration docs:
52
53
  1. `pnpm tsc --noEmit` clean.
53
54
  2. Every `await sodax.api.swaps.<method>(...)` call site has `if (!result.ok)`.
54
55
  3. `submitTx.relayData` is `relayData.payload` (string); `getSubmitTxStatus` passes both `txHash` and `srcChainKey`.
55
- 4. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
56
+ 4. Every `getQuote` / `createIntent` body carries the same `partnerFee` (real receiver), or the user said they are not monetizing.
57
+ 5. Intent-bearing bodies pass the `bigint` `IntentRequestV2` through unmodified (no manual `.toString()`).
56
58
 
57
59
  ## Related granular skills (same family)
58
60
 
@@ -84,7 +84,7 @@ import { SuiWalletProvider } from '@sodax/wallet-sdk-core';
84
84
 
85
85
  // Private-key — DERIVED FROM MNEMONIC, not a raw key
86
86
  const suiPk = new SuiWalletProvider({
87
- rpcUrl: 'https://fullnode.mainnet.sui.io:443',
87
+ rpcUrl: 'https://sui-rpc.publicnode.com',
88
88
  mnemonics: 'word1 word2 … word12',
89
89
  });
90
90