@sodax/skills 2.0.0-rc.7 → 2.0.0-rc.9

package/.claude-plugin/plugin.json

@@ -2,6 +2,15 @@
   "name": "sodax-skills",
   "skills": [
     "./skills/sodax-sdk",
+    "./skills/sodax-sdk/swap",
+    "./skills/sodax-sdk/money-market",
+    "./skills/sodax-sdk/bridge",
+    "./skills/sodax-sdk/staking",
+    "./skills/sodax-sdk/dex",
+    "./skills/sodax-sdk/migration",
+    "./skills/sodax-sdk/partner",
+    "./skills/sodax-sdk/recovery",
+    "./skills/sodax-sdk/backend-api",
     "./skills/sodax-wallet-sdk-core",
     "./skills/sodax-wallet-sdk-react",
     "./skills/sodax-dapp-kit"

package/AGENTS.md

@@ -4,14 +4,16 @@
 
 ## What's here
 
-This package ships **four mode-gated skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package. Each skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
+This package ships **four mode-gated broad skills** (`skills/<name>/SKILL.md`) — one per SODAX SDK package — plus **nested granular per-feature skills** under `sodax-sdk` (one per Core SDK feature service). Each broad skill bundles two long-form **knowledge** subtrees: `integration/knowledge/` (writing new v2 code) and `migration-v1-to-v2/knowledge/` (porting v1 → v2). Granular skills are single-file SKILL.md that link into their parent's knowledge tree. Skills are action-oriented (when to use, workflow, anti-patterns, links into knowledge); knowledge is the reference material your workflow points at. SKILL.md gates by mode at the top — pick integration or migration based on the consumer signal.
 
-| SDK package | Skill |
-|---|---|
-| `@sodax/sdk` | `sodax-sdk` |
-| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` |
-| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` |
-| `@sodax/dapp-kit` | `sodax-dapp-kit` |
+| SDK package | Broad skill | Granular per-feature skills |
+|---|---|---|
+| `@sodax/sdk` | `sodax-sdk` | `sodax-sdk/swap`, `sodax-sdk/money-market`, `sodax-sdk/bridge`, `sodax-sdk/staking`, `sodax-sdk/dex`, `sodax-sdk/migration`, `sodax-sdk/partner`, `sodax-sdk/recovery`, `sodax-sdk/backend-api` |
+| `@sodax/wallet-sdk-core` | `sodax-wallet-sdk-core` | — |
+| `@sodax/wallet-sdk-react` | `sodax-wallet-sdk-react` | — |
+| `@sodax/dapp-kit` | `sodax-dapp-kit` | — |
+
+**When to prefer a granular skill:** if the consumer has already picked a feature (e.g. *"swap with Sodax"*, *"supply on money market"*), load the matching granular skill — it's ~3 KB vs `sodax-sdk`'s ~13 KB and points at exactly the knowledge files needed for that feature. Load the broad `sodax-sdk` skill when the feature is undecided, the task spans multiple features, or the consumer is porting a full v1 codebase.
 
 > **What about `@sodax/types`?** No skill. The package has no consumer-facing surface — it's pure TypeScript types, re-exported through `@sodax/sdk`. Importing `@sodax/types` directly invites version skew. The SDK skills cover all `@sodax/types` symbols you need.
 
@@ -21,6 +23,7 @@ Pick the consumer's situation, load the listed skills in order. Each entry names
 
 | Consumer is… | Load skills (mode) |
 |---|---|
+| **Scaffolding ONE specific Core SDK feature** (swap, money-market, bridge, staking, dex, migration, partner, recovery, backend-api) | `sodax-sdk/<feature>` (granular, covers both modes via internal links). Add `sodax-wallet-sdk-core` (integration) if it signs and lives outside React. Skip the broad `sodax-sdk` skill |
 | **Building a NEW React dapp** | `sodax-wallet-sdk-react` (integration) → `sodax-dapp-kit` (integration) → (`sodax-sdk` (integration) only if dropping below dapp-kit) |
 | **Building a NEW React app, no dapp-kit** (calling the SDK directly) | `sodax-wallet-sdk-react` (integration) → `sodax-sdk` (integration) |
 | **Building a NEW Node / backend service or script** | `sodax-sdk` (integration) → `sodax-wallet-sdk-core` (integration; only if it signs) |
@@ -49,9 +52,11 @@ Each `SKILL.md` is short on purpose. Follow it like a procedure:
 ```
 packages/skills/
 ├── AGENTS.md                              # You are here
-├── .claude-plugin/plugin.json             # Skill registry (4 entries)
-└── skills/                                # Each skill is mode-gated: SKILL.md + two knowledge subtrees
-    ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
+├── .claude-plugin/plugin.json             # Skill registry (broad + nested granular paths)
+└── skills/                                # Each broad skill is mode-gated; some have nested granular children
+    ├── sodax-sdk/                         {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/,
+    │                                       <feature>/SKILL.md ×9 — swap, money-market, bridge, staking, dex,
+    │                                       migration, partner, recovery, backend-api}
     ├── sodax-wallet-sdk-core/             {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}
     ├── sodax-wallet-sdk-react/            {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/ — incl. 4 .tsx example apps under integration/knowledge/examples/}
     └── sodax-dapp-kit/                    {SKILL.md, integration/knowledge/, migration-v1-to-v2/knowledge/}

package/package.json

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

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

@@ -115,4 +115,4 @@ await approve({ params: bnUSDParams, walletProvider, action: 'migrate' });
 
 - [`../recipes/migration.md`](../recipes/migration.md) — full worked examples.
 - [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md) — v1 → v2 porting (the v1 dapp-kit had a single `useMigrate(spokeProvider)`-style hook; v2 split into 6).
-- `sodax-sdk`: `integration/knowledge/features/icx-bnusd-baln.md` — underlying SDK migration surface.
+- `sodax-sdk`: `integration/knowledge/features/migration.md` — underlying SDK migration surface.

package/skills/sodax-dapp-kit/migration-v1-to-v2/knowledge/features/migration.md

@@ -117,4 +117,4 @@ The biggest single API change in dapp-kit v2: v1 had a single `useMigrate(spokeP
 
 - [`features/migration.md`](../../../integration/knowledge/features/migration.md) — v2 reference.
 - [`recipes/migration.md`](../../../integration/knowledge/recipes/migration.md) — full v2 worked examples (ICX, BALN, bnUSD, revert).
-- `sodax-sdk`: `migration-v1-to-v2/knowledge/features/icx-bnusd-baln.md` — underlying SDK migration migration.
+- `sodax-sdk`: `migration-v1-to-v2/knowledge/features/migration.md` — underlying SDK migration migration.

package/skills/sodax-sdk/SKILL.md

@@ -15,6 +15,46 @@ AGENTS.md routes you here when you're working with `@sodax/sdk` v2 — either wr
 
 For React dapps using hooks → use `sodax-dapp-kit` instead (this skill is still relevant for any unwrapped SDK call).
 
+## Prefer a granular skill if the feature is known
+
+If the user has already picked a single feature, load the matching granular skill instead of this broad one — it loads ~3 KB of focused workflow vs this file's ~13 KB and links directly into the right knowledge files. The granular skills sit in the same family (`sdk`) and cover both integration and migration via internal cross-links.
+
+| Feature | Granular skill | Trigger phrases |
+|---|---|---|
+| Intent-based swap (market + limit orders) | [`./swap/SKILL.md`](./swap/SKILL.md) | "swap with Sodax", "limit order", "cancel intent" |
+| Cross-chain lending / borrowing | [`./money-market/SKILL.md`](./money-market/SKILL.md) | "supply", "borrow", "withdraw collateral", "repay" |
+| Direct token bridge via vault | [`./bridge/SKILL.md`](./bridge/SKILL.md) | "bridge tokens", "cross-chain transfer" |
+| SODA ↔ xSoda staking | [`./staking/SKILL.md`](./staking/SKILL.md) | "stake SODA", "instant unstake", "claim staking rewards" |
+| Concentrated-liquidity LP | [`./dex/SKILL.md`](./dex/SKILL.md) | "LP position", "concentrated liquidity", "deposit hub assets" |
+| ICX / bnUSD / BALN token migration to SODAX | [`./migration/SKILL.md`](./migration/SKILL.md) | "migrate ICX", "legacy bnUSD", "BALN lockup" (NOT v1→v2 SDK porting) |
+| Partner fees | [`./partner/SKILL.md`](./partner/SKILL.md) | "claim partner fee", "partner auto-swap preference", "approve partner fee token" |
+| Stuck-asset recovery | [`./recovery/SKILL.md`](./recovery/SKILL.md) | "recover stuck assets on Sonic", "RecoveryService", "withdrawHubAsset" |
+| 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" |
+
+Load this broad skill (keep reading below) when:
+
+- The feature is not yet decided.
+- The task spans **multiple** features (e.g. swap + money-market in one flow).
+- The consumer is doing a **full v1 → v2 port** of an existing codebase.
+
+## Out of scope
+
+This skill documents the **SDK call sites** — what to import, how to construct `Sodax`, which method to call, and how to handle the `Result<T>`. It does **not** prescribe application-layer concerns.
+
+### Where to go for the things this skill does NOT cover
+
+- **Wallet provider implementations** (`IEvmWalletProvider`, `ISolanaWalletProvider`, etc.) → **load the `sodax-wallet-sdk-core` skill** (integration mode). It ships ready-made provider classes for all 9 chain families, both private-key (Node / scripts) and browser-extension modes. This skill only treats wallet providers as a contract (`declare const evmWallet: IEvmWalletProvider`).
+- **React hooks wrapping the SDK** → **load the `sodax-dapp-kit` skill** instead of this one.
+- **Browser wallet connectivity** (connect / disconnect / chain switching for React apps) → **load the `sodax-wallet-sdk-react` skill**.
+
+### App-layer concerns the SDK is intentionally silent on
+
+- **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.
+- **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.
+- **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.
+
+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.
+
 ---
 
 ## Integration mode (writing new v2 code)
@@ -31,7 +71,7 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
 
 1. Read [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — DO / DO NOT / workflow / stop conditions.
 2. Read [`integration/knowledge/quickstart.md`](./integration/knowledge/quickstart.md) — install, initialize, first-run troubleshooting.
-3. For your feature, read [`integration/knowledge/features/`](./integration/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `icx-bnusd-baln.md`, `auxiliary-services.md`.
+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`.
 4. For specific patterns (init, raw vs signed, chain narrowing, gas, testing, errors), read [`integration/knowledge/recipes/`](./integration/knowledge/recipes/).
 5. Lookups (chain keys, error codes, public API surface, wallet provider types, glossary) → [`integration/knowledge/reference/`](./integration/knowledge/reference/).
 6. Non-EVM quirks (Stellar trustline, BTC PSBT, Solana PDA, ICON, NEAR) → [`integration/knowledge/chain-specifics.md`](./integration/knowledge/chain-specifics.md).
@@ -44,29 +84,9 @@ Follow in order. Skipping `ai-rules.md` is the most common cause of agents rever
 4. **Signed vs raw is a discriminated union.** `WalletProviderSlot<K, Raw>` enforces at compile time: `{ raw: false, walletProvider }` for signing, `{ raw: true }` for unsigned-tx building. Mixing them is a TypeScript error.
 5. **Config is dynamic; overrides only land on `sodax.config`.** Always read via `sodax.config.*` (e.g. `sodax.config.spokeChainConfig[chainKey]`). Direct imports of `spokeChainConfig` / `sodaxConfig` from `@sodax/types` / `@sodax/sdk` are packaged-default snapshots and silently miss both `await sodax.config.initialize()` updates and `new Sodax(config)` overrides.
 
-### Top traps to avoid (integration)
-
-1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass an object satisfying the chain-specific `I*WalletProvider` interface directly into the SDK call payload. Implementations come from your application — write your own or install `@sodax/wallet-sdk-core`.
-2. **Forgetting `raw: false`.** Without the discriminator, `walletProvider` is rejected with "Object literal may only specify known properties." Add `raw: false` for signed flows; `raw: true` for unsigned-tx building.
-3. **Importing from `@sodax/types` directly.** `@sodax/sdk` re-exports the entire `@sodax/types` surface. Add `@sodax/sdk` as your only dependency; importing `@sodax/types` separately risks version skew.
-4. **Treating `Result<T>` as throw-on-failure.** v2 mutation methods do **not** throw on SDK-level failure — they resolve `{ ok: false, error }`. A `try/catch` only catches *exceptions* from inside `mutationFn` (e.g. missing `walletProvider`); it will **not** catch `RELAY_TIMEOUT` or `EXECUTION_FAILED`. Branch on `.ok`.
-5. **Reading `xToken.xChainId` or hard-coding `*_MAINNET_CHAIN_ID`.** Renamed: `XToken.chainKey` and `ChainKeys.*`. v1 numeric/string chain-id constants are gone.
-
-### Conventions agents must follow (integration)
+### Top traps, conventions, verification
 
-- **`Result<T>` discrimination on `.ok`.** Always branch on `result.ok` before reading `.value` or `.error`. Forward sub-Results without re-wrapping (`if (!sub.ok) return sub`).
-- **`(feature, code)` for error switching.** Use `isSodaxError(e)`, then `e.feature` and `e.code` for routing logic. Don't string-match on `e.message`.
-- **`ChainKeys.*` over hard-coded strings.** The set of supported chains evolves per release.
-- **No `as unknown as <Type>` double-casts.** v2 type narrowing makes them unnecessary — chain-key generic flow + `GetWalletProviderType<K>` resolves to the exact interface.
-- **Don't generate `try { await sodax.<method>(...) } catch` for SDK-level failures.** That catch never fires for `Result.!ok`. Branch on `result.ok`.
-- Import only from the package root: `import { Sodax, ChainKeys, type SpokeChainKey } from '@sodax/sdk'`. Don't deep-import from `dist/...`.
-
-### Verification (integration)
-
-1. `pnpm tsc --noEmit` from the consumer repo — must exit clean.
-2. Every `await sodax.<feature>.<method>(...)` call site has `if (!result.ok)` branching.
-3. No `xToken.xChainId`, no `*_MAINNET_CHAIN_ID`, no `*SpokeProvider` references.
-4. `isSodaxError(e)` (not bare `instanceof SodaxError`) in cross-bundle code.
+The DO / DO NOT / verification checklist lives in [`integration/knowledge/ai-rules.md`](./integration/knowledge/ai-rules.md) — read it before writing any call site. The biggest source of generated v1-style code is skipping it.
 
 ---
 
@@ -89,7 +109,7 @@ If the consumer has v1 fingerprints AND also wants new features: **do migration
    - [`breaking-changes/type-system.md`](./migration-v1-to-v2/knowledge/breaking-changes/type-system.md) — renames at `@sodax/types`, `ChainKeys`, `WalletProviderSlot`, `RpcConfig`, `IConfigApi` Result.
    - [`breaking-changes/architecture.md`](./migration-v1-to-v2/knowledge/breaking-changes/architecture.md) — `*SpokeProvider` deletion, `ConfigService`, relay reshape.
    - [`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.
-4. **Per-feature playbooks** under [`features/`](./migration-v1-to-v2/knowledge/features/) — `swap.md`, `money-market.md`, `staking.md`, `bridge.md`, `dex.md`, `icx-bnusd-baln.md`, `auxiliary-services.md` — read only the ones the consumer uses.
+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.
 5. **Codemods + adapters** for mechanical replacement → [`recipes.md`](./migration-v1-to-v2/knowledge/recipes.md).
 6. **Cross-check** symbols in [`reference/`](./migration-v1-to-v2/knowledge/reference/) — `deleted-exports.md`, `error-code-crosswalk.md`, `return-shapes.md`, `sodax-config.md`.
 
@@ -107,30 +127,9 @@ Apply in this order — type-level changes don't affect behavior; runtime patter
 
 Then on every signed-call payload: drop `spokeProvider`, add `walletProvider`, add `raw: false` discriminator, rename `intentParams` → `params`. Plus add `srcChainKey` + `srcAddress` to every action params object (MM, staking, deposit, …).
 
-### Top traps to avoid (migration)
-
-1. **Reaching for a `*SpokeProvider`.** They're deleted. Pass `walletProvider` (an `I*WalletProvider` impl) directly in the call payload.
-2. **`instanceof MoneyMarketError` (and other module error classes).** Deleted. Replace with `isSodaxError(e) && e.feature === 'moneyMarket'`.
-3. **Destructuring cross-chain results as arrays.** v1 had `bridge()` returning a string and others returning tuples; v2 returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for **every** cross-chain mutation. Destructure as `{ srcChainTxHash, dstChainTxHash } = result.value`.
-4. **Keeping `try/catch` to inspect v1 error codes.** v2 returns `Result<T>` — failure lives on `result.error.code`, not on a thrown error. The v2 code names changed too — see `reference/error-code-crosswalk.md`.
-5. **Calling `getStakingInfo(hubAddress)`.** Renamed to `getStakingInfoFromSpoke(srcAddress, srcChainKey)`. `getStakingInfo` is not a public method anymore.
-
-### DO NOT
-
-- Grep-replace `srcChain` → `srcChainKey` blindly. The `Intent` read shape keeps `srcChain` / `dstChain` as `IntentRelayChainId` (bigint). Only **request** types changed.
-- Assume `BalnSwapService` lock methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw — known carve-out. Keep `try/catch` for those specific calls.
-- Add `@sodax/types` as a peer dependency. It's bundled into `@sodax/sdk`'s public surface.
-
-### Verification (migration)
-
-```bash
-pnpm tsc --noEmit    # must exit clean
-# No leftover v1 fingerprints:
-grep -rE '_MAINNET_CHAIN_ID\b|\bxChainId\b|\bSpokeChainId\b|\bSpokeProvider\b|hubAssets|moneyMarketSupportedTokens' src/   # empty
-grep -rE 'MoneyMarketError|IntentError|StakingError|BridgeError|MigrationError|AssetServiceError|ConcentratedLiquidityError|RelayError' src/   # empty
-```
+### Top traps, DO NOT, verification
 
-Every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching (highest-leverage change — if you stop early, ensure result branching is at least in place).
+The full DO / DO NOT list, mode-specific pitfalls, and verification protocol live in [`migration-v1-to-v2/knowledge/ai-rules.md`](./migration-v1-to-v2/knowledge/ai-rules.md) — read it before touching any call site. Highest-leverage rule: every `await sodax.<feature>.<method>(...)` call site must have `if (!result.ok)` branching.
 
 ---
 

package/skills/sodax-sdk/backend-api/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: sodax-sdk-backend-api
+description: 'Granular skill for the @sodax/sdk v2 BackendApiService — HTTP client to the SODAX backend for intent lookup, swap-tx submission, solver orderbook, money-market position/reserve reads, and (internally) config fetching. Use when the task touches a backend read or write (e.g. "submit swap tx to Sodax backend", "Sodax getIntentByHash", "fetch money market position from Sodax backend", "Sodax orderbook", "Sodax BackendApiService", "implement custom IConfigApi sandbox"). Covers BOTH integration and the load-bearing v1 → v2 Result-wrapping migration. Skill links into the parent sodax-sdk knowledge tree.'
+---
+
+# Backend API (Core SDK granular skill)
+
+Granular skill for `BackendApiService` — `sodax.backendApi`. HTTP client used by every feature for reads + swap-tx submission. **Feature tag for errors** varies by call site (e.g. `'swap'` for `submitSwapTx`, `'moneyMarket'` for MM reads); errors always carry `error.context.api: 'backend'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?** Note: v2's load-bearing change is `Result`-wrapping every method (v1 threw on failure).
+2. **Which category?**
+   - **Swap-related reads / writes:** `submitSwapTx`, `getSubmitSwapTxStatus`, `getOrderbook`, `getIntentByHash`, `getIntentByTxHash`, `getUserIntents`.
+   - **Money-market position reads:** `getMoneyMarketPosition`, `getAllMoneyMarketAssets`, `getMoneyMarketAsset`, `getMoneyMarketAssetBorrowers`, `getMoneyMarketAssetSuppliers`, `getAllMoneyMarketBorrowers`.
+   - **Config-API methods (implements `IConfigApi`):** `getAllConfig`, `getChains`, `getSwapTokens`, `getSwapTokensByChainId`, `getMoneyMarketTokens`, `getMoneyMarketReserveAssets`, `getMoneyMarketTokensByChainId`, `getRelayChainIdMap`.
+3. **Custom `IConfigApi` for sandbox / fixtures?** Every method must return `Promise<Result<T>>` in v2.
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/backend-api.md`](../integration/knowledge/features/backend-api.md) — `BackendApiService` API + `submitSwapTx` call shape + custom-backend pattern.
+3. For the `submitSwapTx` + `createIntent` flow → also load [`../swap/SKILL.md`](../swap/SKILL.md) or read [`../integration/knowledge/features/swap.md`](../integration/knowledge/features/swap.md) § "Backend submit-tx flow".
+4. Errors carry `error.context.api === 'backend'` → [`../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).
+
+### Backend-API-specific anti-patterns
+
+- **Passing the `RelayExtraData` object** to `submitSwapTx.relayData`. The field is now `string` — pass `relayData.payload`.
+- **Using v1 `srcChainId` (numeric)** on `SubmitSwapTxRequest`. Renamed to `srcChainKey: SpokeChainKey`.
+- **Implementing `IConfigApi` with throw-on-error semantics.** v2 interface requires `Promise<Result<T>>` — every method.
+- **Reading money-market position from `MoneyMarketService`.** Those reads live here on `BackendApiService`.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/backend-api.md`](../migration-v1-to-v2/knowledge/features/backend-api.md) — the load-bearing change: every method now returns `Promise<Result<T>>`. Includes the `submitSwapTx` request-shape changes (`srcChainId` → `srcChainKey`, `relayData` object → string) and the `IConfigApi` sandbox-impl change.
+3. Cross-cutting `IConfigApi` Result-wrapping note → [`../migration-v1-to-v2/knowledge/breaking-changes/type-system.md`](../migration-v1-to-v2/knowledge/breaking-changes/type-system.md) § 6.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.backendApi.<method>(...)` has `if (!result.ok)`.
+3. `SubmitSwapTxRequest` uses `srcChainKey` (not `srcChainId`) and `relayData: relayData.payload` (string).
+4. Any custom `IConfigApi` implementation returns `Promise<Result<T>>` from every method.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — `submitSwapTx` is the backend half of the step-by-step swap flow.
+- [`../money-market/SKILL.md`](../money-market/SKILL.md) — `BackendApiService` is the canonical source of MM position reads.
+- [`../partner/SKILL.md`](../partner/SKILL.md), [`../recovery/SKILL.md`](../recovery/SKILL.md) — diagnostics for failures via intent / tx lookups.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/bridge/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: sodax-sdk-bridge
+description: 'Granular skill for the @sodax/sdk v2 bridge feature only — cross-chain token transfer via vault. Use when the task is specifically bridging (e.g. "bridge tokens cross-chain with Sodax", "Sodax bridge", "transfer USDC from Arbitrum to Stellar via Sodax", "check bridgeable amount"). The bridge() method returns `TxHashPair = { srcChainTxHash, dstChainTxHash }` for every cross-chain mutation. Covers BOTH integration (new v2 code) and migration (port v1 BridgeService). Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# Bridge (Core SDK granular skill)
+
+Granular skill for `BridgeService` — `sodax.bridge`. Feature tag: `'bridge'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Signed flow (frontend) or unsigned-tx (backend)?**
+3. **Need a bridgeable-amount precheck?** Vault deposit limits may cap the transfer; `getBridgeableAmount` (or equivalent) read tells you the cap before submitting.
+4. **Source / destination chains** — confirm both are supported spoke chains, and the destination address format matches the chain (vd Stellar address starts with `G`, Solana base58, Bitcoin specific encodings).
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/bridge.md`](../integration/knowledge/features/bridge.md) — API surface, `TxHashPair` return shape, bridgeable-amount reads.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Destination-chain quirks (Stellar trustline, BTC PSBT, Solana PDA) → [`../integration/knowledge/chain-specifics.md`](../integration/knowledge/chain-specifics.md).
+5. Errors (`feature: 'bridge'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### Bridge-specific anti-patterns
+
+- **Destructuring the return as an array or single hash.** v2 ALWAYS returns `{ srcChainTxHash, dstChainTxHash }` for cross-chain mutations — destructure by name.
+- **Skipping the bridgeable-amount check.** Submitting an amount over the vault cap returns `EXECUTION_FAILED`; cheaper to check first.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/bridge.md`](../migration-v1-to-v2/knowledge/features/bridge.md) — v1 `bridge()` returned a string; v2 returns `TxHashPair`. Update all destructuring sites.
+3. v1 `BridgeError` → v2 `SodaxError<C>` with `feature: 'bridge'`.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.bridge.<method>(...)` has `if (!result.ok)`.
+3. No string-typed return destructuring at `bridge()` call sites.
+
+## Related granular skills (same family)
+
+- [`../swap/SKILL.md`](../swap/SKILL.md) — for intent-based cross-chain swaps (different from a direct bridge: swap goes via a solver).
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck assets on the hub.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/dex/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: sodax-sdk-dex
+description: 'Granular skill for the @sodax/sdk v2 DEX feature only — Uniswap-V3-style concentrated liquidity positions on the hub, plus AssetService for hub-asset deposit/withdraw. Use when the task is LP positions (e.g. "Sodax concentrated liquidity", "create LP position on Sodax", "increase liquidity", "decrease liquidity", "claim LP fees", "deposit hub assets for LP"). Covers BOTH integration and migration. Skill links into the parent sodax-sdk knowledge tree. For React dapps, prefer sodax-dapp-kit.'
+---
+
+# DEX (Core SDK granular skill)
+
+Granular skill for `DexService` — facade owning `clService: ClService` (concentrated liquidity) and `assetService: AssetService` (hub-asset deposit/withdraw). Access via `sodax.dex.clService` and `sodax.dex.assetService`. Feature tag for errors: `'dex'`.
+
+## Step 1 — Clarify with user before coding
+
+1. **New code or v1 → v2 port?**
+2. **Which operation?**
+   - LP: `createPosition`, `increaseLiquidity`, `decreaseLiquidity`, `claimFees`, `closePosition`.
+   - Assets: `deposit` (spoke → hub-asset wrapper), `withdraw` (hub → spoke).
+3. **Does the position require an asset deposit first?** LP positions hold hub assets; the user must deposit from a spoke chain before opening a position.
+4. **Signed or unsigned-tx flow?**
+
+## Integration workflow
+
+1. [`../integration/knowledge/ai-rules.md`](../integration/knowledge/ai-rules.md).
+2. [`../integration/knowledge/features/dex.md`](../integration/knowledge/features/dex.md) — `ClService` + `AssetService` APIs, position lifecycle, tick math notes.
+3. Path-specific recipe:
+   - Signed → [`../integration/knowledge/recipes/signed-tx-flow.md`](../integration/knowledge/recipes/signed-tx-flow.md)
+   - Unsigned → [`../integration/knowledge/recipes/raw-tx-flow.md`](../integration/knowledge/recipes/raw-tx-flow.md)
+4. Errors (`feature: 'dex'`) → [`../integration/knowledge/reference/error-codes.md`](../integration/knowledge/reference/error-codes.md).
+
+### DEX-specific anti-patterns
+
+- **Reaching for `sodax.cl` / `sodax.assets`.** Wrong paths — both services are reached via `sodax.dex` (i.e. `sodax.dex.clService.*` and `sodax.dex.assetService.*`). The `Sodax` facade exposes only `dex`.
+- **Skipping `assetService.deposit` before opening a position.** LP positions reference hub-asset addresses; without deposit there's nothing to provide.
+- **Confusing pool addresses on Sonic with spoke token addresses.** CL pools live on Sonic; the user-facing tokens live on spokes.
+
+## Migration workflow (v1 → v2)
+
+1. [`../migration-v1-to-v2/knowledge/ai-rules.md`](../migration-v1-to-v2/knowledge/ai-rules.md).
+2. [`../migration-v1-to-v2/knowledge/features/dex.md`](../migration-v1-to-v2/knowledge/features/dex.md) — v1 `ConcentratedLiquidityError` / `AssetServiceError` → v2 `SodaxError<C>` with the appropriate `feature` tag.
+
+## Verification
+
+1. `pnpm tsc --noEmit` clean.
+2. Every `await sodax.dex.clService.<method>(...)` and `await sodax.dex.assetService.<method>(...)` has `if (!result.ok)`.
+3. No `instanceof ConcentratedLiquidityError` / `AssetServiceError`.
+
+## Related granular skills (same family)
+
+- [`../recovery/SKILL.md`](../recovery/SKILL.md) — `RecoveryService` for stuck hub-wallet LP assets.
+- [`../backend-api/SKILL.md`](../backend-api/SKILL.md) — `BackendApiService` for position reads if surfaced there.
+
+For multi-feature tasks, load the broad [`sodax-sdk` skill](../SKILL.md).

package/skills/sodax-sdk/integration/knowledge/README.md

@@ -13,8 +13,10 @@ This tree documents v2 of the SDK for **new consumers** building against it. If
 | [`features/staking.md`](features/staking.md) | `StakingService`: SODA → xSoda — stake, unstake, instant unstake, claim, cancel; ratio + info reads. |
 | [`features/bridge.md`](features/bridge.md) | `BridgeService`: cross-chain token transfer via vault — `bridge`, `createBridgeIntent`, `getBridgeableAmount`, `getBridgeableTokens`. |
 | [`features/dex.md`](features/dex.md) | `ClService` (concentrated liquidity) + `AssetService`: position lifecycle (mint/increase/decrease), claim rewards, asset deposit/withdraw. |
-| [`features/icx-bnusd-baln.md`](features/icx-bnusd-baln.md) | `MigrationService` (the SDK module): ICX, bnUSD, BALN sub-services + lock management. |
-| [`features/auxiliary-services.md`](features/auxiliary-services.md) | `PartnerService` + `RecoveryService` + `BackendApiService` — small APIs grouped together. |
+| [`features/migration.md`](features/migration.md) | `MigrationService` (the SDK module): ICX, bnUSD, BALN sub-services + lock management. |
+| [`features/partner.md`](features/partner.md) | `PartnerService` — partner-fee handling. |
+| [`features/recovery.md`](features/recovery.md) | `RecoveryService` — withdraw stuck hub-wallet assets. |
+| [`features/backend-api.md`](features/backend-api.md) | `BackendApiService` — HTTP client for backend reads + swap-tx submission. |
 | [`recipes/`](recipes/) | Copy-pasteable patterns: SDK initialization, `Result` + error discrimination, raw-tx flow, signed-tx flow, chain-key narrowing + cast-at-boundary, testing (mocks/stubs), gas estimation, backend-server init. |
 | [`reference/`](reference/) | Lookup tables: 20-chain `ChainKeys` table with family + relay id, `I*WalletProvider` interfaces, 13 `SodaxErrorCode` meanings + per-feature narrow unions, public API surface (incl. `@sodax/types` re-export rule), glossary. |
 | [`chain-specifics.md`](chain-specifics.md) | Non-EVM quirks — Stellar trustline check/request, Bitcoin PSBT + Radfi auth/session, Solana PDA derivation, ICON Hana wallet + chain-key string, NEAR connector discovery. |

package/skills/sodax-sdk/integration/knowledge/ai-rules.md

@@ -32,7 +32,7 @@ DO / DO NOT / workflow / stop conditions for AI agents writing `@sodax/sdk` v2 c
 - **DO NOT** import from `@sodax/sdk/dist/...`. Deep imports are unstable across releases; only the package root barrel is the public contract.
 - **DO NOT** add `@sodax/types` as a separate dependency. It's bundled / re-exported via `@sodax/sdk`. Adding it independently invites version skew.
 - **DO NOT** destructure cross-chain mutation results as arrays — `[a, b] = result.value` is wrong. The shape is `TxHashPair = { srcChainTxHash, dstChainTxHash }` (object). This applies to `bridge.bridge`, `staking.{stake,unstake,instantUnstake,claim,cancelUnstake}`, `dex.assetService.{deposit,withdraw}`, `dex.clService.{supplyLiquidity,increaseLiquidity,decreaseLiquidity,claimRewards}`, `moneyMarket.{supply,borrow,withdraw,repay}`, `migration.{migratebnUSD,migrateIcxToSoda,revertMigrateSodaToIcx,migrateBaln}` — all of them.
-- **DO NOT** treat method names from `MoneyMarketService` as the source of MM reads. `getReservesData`, `getUserReservesData`, `getATokensBalances`, etc. live on `sodax.backendApi`, not `sodax.moneyMarket`. See [`features/auxiliary-services.md`](features/auxiliary-services.md) § "BackendApiService".
+- **DO NOT** treat method names from `MoneyMarketService` as the source of MM reads. `getReservesData`, `getUserReservesData`, `getATokensBalances`, etc. live on `sodax.backendApi`, not `sodax.moneyMarket`. See [`features/backend-api.md`](features/backend-api.md).
 - **DO NOT** reach for an `intentRelayApi` property on the `Sodax` instance — there is no such property. The relay layer is exposed as two top-level functions, `relayTxAndWaitPacket` and `submitTransaction` (re-exported from `@sodax/sdk`). Call them directly if you need custom relay orchestration.
 - **DO NOT** call `getStakeRatio` and treat its return as `Result<bigint>`. It's `Result<[xSodaAmount, previewDepositAmount]>` — a tuple of two bigints.
 - **DO NOT** assume `BalnSwapService` lock-management methods (`stake`, `unstake`, `claim`, `claimUnstaked`, `cancelUnstake`, `getDetailedUserLocks`) return `Result<T>`. They still throw on error in v2 — known carve-out. Wrap them in `try/catch`.

package/skills/sodax-sdk/integration/knowledge/architecture.md

@@ -356,23 +356,7 @@ class SodaxError<C extends SodaxErrorCode = SodaxErrorCode> extends Error {
 
 ### The 13 codes
 
-| Code | Meaning |
-|---|---|
-| `VALIDATION_FAILED` | Pre-flight invariant tripped. |
-| `INTENT_CREATION_FAILED` | Building the intent / payload failed. |
-| `EXECUTION_FAILED` | Orchestrator-level catch-all for multi-step ops. |
-| `TX_VERIFICATION_FAILED` | Spoke-side `verifyTxHash` returned false / threw. |
-| `TX_SUBMIT_FAILED` | Spoke tx landed; relay POST submit failed. |
-| `RELAY_TIMEOUT` | Destination packet didn't reach `executed` within timeout. |
-| `RELAY_FAILED` | Relay polling outage / unrecognised relay error. |
-| `APPROVE_FAILED` | Token approval call failed. |
-| `ALLOWANCE_CHECK_FAILED` | Reading on-chain allowance failed. |
-| `GAS_ESTIMATION_FAILED` | Gas estimation returned an error. |
-| `LOOKUP_FAILED` | Read-only on-chain query / off-chain config fetch. |
-| `EXTERNAL_API_ERROR` | Upstream API call failed (solver, backend). |
-| `UNKNOWN` | Last-resort catch in an outer `try`. Should be rare. |
-
-The full per-code semantics, common context fields, per-feature narrow unions, and retry guidance are in [`reference/`](reference/) § "Error codes".
+The closed code vocabulary is the same 13 names across every feature — see [`reference/error-codes.md`](reference/error-codes.md) for the full table, per-code semantics, common `context` field shapes, per-feature narrow unions, and retry guidance.
 
 ### `(feature, code)` discrimination
 
@@ -518,7 +502,7 @@ You drop down to the relay layer only when:
 
 ### Cross-references
 
-- `RecoveryService` for pulling stuck hub-wallet assets back to a spoke chain: see [`features/auxiliary-services.md`](features/auxiliary-services.md).
+- `RecoveryService` for pulling stuck hub-wallet assets back to a spoke chain: see [`features/recovery.md`](features/recovery.md).
 - Per-feature error codes related to relay (e.g. `'TX_SUBMIT_FAILED'`, `'RELAY_TIMEOUT'`): [`reference/`](reference/) § "Error codes".
 
 ---

package/skills/sodax-sdk/integration/knowledge/features/README.md

@@ -9,8 +9,10 @@ One file per feature service. Each file documents the v2 API surface, common cal
 | [`staking.md`](staking.md) | `StakingService` | SODA → xSoda staking via ERC-4626 vault. Stake, unstake (with penalty curve), instant unstake (slippage), claim, cancel. |
 | [`bridge.md`](bridge.md) | `BridgeService` | Cross-chain token transfer via vault. `bridge` returns `TxHashPair = { srcChainTxHash, dstChainTxHash }`. Bridgeable-amount queries respect vault deposit limits. |
 | [`dex.md`](dex.md) | `ClService` + `AssetService` | Uniswap-V3-style concentrated liquidity positions. Asset deposit/withdraw. Increase/decrease/claim flows. |
-| [`icx-bnusd-baln.md`](icx-bnusd-baln.md) | `MigrationService` (the SDK module — not v1→v2 porting) | Legacy ICON ecosystem token migration. ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA with lockup multipliers. |
-| [`auxiliary-services.md`](auxiliary-services.md) | `PartnerService` + `RecoveryService` + `BackendApiService` | Three small APIs grouped together: partner-fee claiming, hub-wallet asset recovery, backend HTTP client. |
+| [`migration.md`](migration.md) | `MigrationService` (the SDK module — not v1→v2 porting) | Legacy ICON ecosystem token migration. ICX ↔ SODA, legacy bnUSD ↔ new bnUSD, BALN → SODA with lockup multipliers. |
+| [`partner.md`](partner.md) | `PartnerService` | Partner-fee handling: token approval, auto-swap preferences, fee-claim flows. |
+| [`recovery.md`](recovery.md) | `RecoveryService` | Withdraw stuck hub-wallet assets back to a spoke chain. |
+| [`backend-api.md`](backend-api.md) | `BackendApiService` | HTTP client for backend services: swap-tx submission, intent / orderbook lookups, money-market reads. |
 
 All feature services are constructed and wired by the `Sodax` facade. You don't instantiate them directly — access them via `sodax.swaps`, `sodax.moneyMarket`, etc. See [`../architecture.md`](../architecture.md) for the service graph.
 

package/skills/sodax-sdk/integration/knowledge/features/backend-api.md

@@ -0,0 +1,81 @@
+# Backend API — `BackendApiService`
+
+HTTP client for backend services. Provides intent lookup, swap-tx submission, solver orderbook queries, money-market position/reserve reads, and (internally) config fetching. Most consumer-side code uses just `submitSwapTx`, `getIntentByHash` / `getIntentByTxHash`, and the money-market read methods.
+
+Access: `sodax.backendApi`. Service class: `BackendApiService`. **Feature tag for errors:** appears under multiple features depending on the call site (`'swap'` for `submitSwapTx`, `'moneyMarket'` for MM-related reads, etc.); errors carry `error.context.api: 'backend'`.
+
+## Methods
+
+```ts
+// Swap-related
+sodax.backendApi.submitSwapTx(request, config?): Promise<Result<SubmitSwapTxResponse>>;
+sodax.backendApi.getSubmitSwapTxStatus(...): Promise<Result<...>>;
+sodax.backendApi.getOrderbook(...): Promise<Result<OrderbookEntry[]>>;
+sodax.backendApi.getIntentByHash(intentHash, config?): Promise<Result<IntentResponse>>;
+sodax.backendApi.getIntentByTxHash(txHash, config?): Promise<Result<IntentResponse>>;
+sodax.backendApi.getUserIntents(...): Promise<Result<IntentResponse[]>>;
+
+// Money-market reads (these are the canonical reads for MM positions/reserves;
+// MoneyMarketService does NOT expose getReservesData / getUserReservesData / etc.)
+sodax.backendApi.getMoneyMarketPosition(...): Promise<Result<...>>;
+sodax.backendApi.getAllMoneyMarketAssets(config?): Promise<Result<MoneyMarketAsset[]>>;
+sodax.backendApi.getMoneyMarketAsset(reserveAddress, config?): Promise<Result<MoneyMarketAsset>>;
+sodax.backendApi.getMoneyMarketAssetBorrowers(...): Promise<Result<...>>;
+sodax.backendApi.getMoneyMarketAssetSuppliers(...): Promise<Result<...>>;
+sodax.backendApi.getAllMoneyMarketBorrowers(...): Promise<Result<...>>;
+
+// Config-API methods (used internally by ConfigService — implements `IConfigApi`)
+sodax.backendApi.getAllConfig(config?): Promise<Result<GetAllConfigApiResponse>>;
+sodax.backendApi.getChains(config?): Promise<Result<GetChainsApiResponse>>;
+sodax.backendApi.getSwapTokens(config?): Promise<Result<GetSwapTokensApiResponse>>;
+sodax.backendApi.getSwapTokensByChainId(...): Promise<Result<XToken[]>>;
+sodax.backendApi.getMoneyMarketTokens(config?): Promise<Result<GetMoneyMarketTokensApiResponse>>;
+sodax.backendApi.getMoneyMarketReserveAssets(...): Promise<Result<...>>;
+sodax.backendApi.getMoneyMarketTokensByChainId(...): Promise<Result<XToken[]>>;
+sodax.backendApi.getRelayChainIdMap(config?): Promise<Result<GetRelayChainIdMapApiResponse>>;
+```
+
+All methods return `Result<T, SodaxError>` where the error carries `feature: 'swap' | 'moneyMarket' | …` (depending on call site) and `error.context.api === 'backend'`.
+
+## Common call shape — `submitSwapTx`
+
+After `sodax.swaps.createIntent({ params, raw: false, walletProvider })` returns:
+
+```ts
+const submitResult = await sodax.backendApi.submitSwapTx({
+  txHash: spokeTxHash as string,
+  srcChainKey: src.chain,
+  walletAddress: '0x…',
+  intent: swapIntentData,
+  relayData: relayData.payload,    // string, not the RelayExtraData object
+});
+
+if (!submitResult.ok) return;
+```
+
+## Custom backend (sandbox / fixtures)
+
+`SodaxConfig` does not expose a typed slot to inject a custom `IConfigApi` implementation at construction. Two supported patterns:
+
+1. **Point at a local mock backend** via `SodaxConfig.api.baseURL`:
+
+   ```ts
+   const sodax = new Sodax({
+     api: { baseURL: 'http://localhost:4000' },
+   });
+   await sodax.config.initialize();
+   ```
+
+   `SodaxConfig.api` is `ApiConfig` (`{ baseURL, timeout, headers }`) — pass any subset via `DeepPartial`.
+
+2. **Inject your own `BackendApiService`-compatible mock at the app layer** (dependency-injected where you control the `Sodax` instance), rather than via the constructor.
+
+The `IConfigApi` interface itself still matters for both patterns — every method returns `Promise<Result<T>>` in v2, so any mock or local server must conform. See [`../architecture.md`](../architecture.md) § 4 "Custom backend" for the authoritative reference.
+
+## Cross-references
+
+- v1 → v2 migration of `BackendApiService` (the load-bearing change: every method now returns `Promise<Result<T>>`): [`features/backend-api.md`](../../../migration-v1-to-v2/knowledge/features/backend-api.md).
+- The full `submitSwapTx` flow with `createIntent` upstream: [`./swap.md`](swap.md) § "Backend submit-tx flow".
+- Partner-fee handling (separate service): [`./partner.md`](partner.md).
+- Stuck-asset recovery (separate service): [`./recovery.md`](recovery.md).
+- Error model context fields (`error.context.api`, `error.context.method`): [`../reference/`](../reference/) § 3.

package/skills/sodax-sdk/integration/knowledge/features/bridge.md

@@ -76,6 +76,42 @@ const { tx, intent, relayData } = result.value;
 // Submit relayData.payload via your own relay infrastructure if needed.
 ```
 
+### Hub as source (Sonic → spoke)
+
+`srcChainKey` accepts `ChainKeys.SONIC_MAINNET` too — the SDK routes through the user's hub-wallet abstraction (instead of a spoke deposit) and then triggers the destination withdrawal. The call shape is the same; only the chain key changes:
+
+```ts
+const sodaSonic = sodax.config.findSupportedTokenBySymbol(ChainKeys.SONIC_MAINNET, 'SODA');
+const sodaBase  = sodax.config.findSupportedTokenBySymbol(ChainKeys.BASE_MAINNET,  'SODA');
+if (!sodaSonic || !sodaBase) throw new Error('SODA missing from config');
+
+// 1. Confirm the pair is vault-bridgeable (synchronous, config-derived).
+if (!sodax.bridge.isBridgeable({ from: sodaSonic, to: sodaBase })) {
+  // Fall back to swap if needed — different vaults aren't bridgeable.
+  return;
+}
+
+// 2. (Optional) check the vault-side cap.
+const limit = await sodax.bridge.getBridgeableAmount(sodaSonic, sodaBase);
+
+// 3. Execute. srcChainKey is the hub.
+const result = await sodax.bridge.bridge({
+  params: {
+    srcChainKey: ChainKeys.SONIC_MAINNET,
+    srcAddress: (await evmWp.getWalletAddress()) as `0x${string}`,
+    srcAsset: sodaSonic.address,
+    amount: parseUnits('1', sodaSonic.decimals),
+    dstChainKey: ChainKeys.BASE_MAINNET,
+    dstAddress: recipientOnBase,
+    dstAsset: sodaBase.address,
+  },
+  raw: false,
+  walletProvider: evmWp,
+});
+```
+
+Internally `bridge()` branches on `isHubChainKeyType(srcChainKey)` and uses the user's hub wallet abstraction as the spender (the assetManager spoke address is used for non-hub sources). For allowance and approval flows, treat Sonic-as-source the same as any other EVM source — `isAllowanceValid` and `approve` use the same parameter shape.
+
 ### Bridgeable-amount check
 
 Respects vault deposit limits (spoke→hub) and asset-manager balance (hub→spoke). Pass the source and destination tokens as full `XToken` objects (each carries its own `chainKey`):

package/skills/sodax-sdk/integration/knowledge/features/{icx-bnusd-baln.md → migration.md}

@@ -8,7 +8,7 @@ Migration of legacy ICON ecosystem tokens to the SODAX hub. Three sub-services:
 
 Access: `sodax.migration`. Service class: `MigrationService` (with sub-services `sodax.migration.icxMigration`, `sodax.migration.bnUSDMigrationService`, `sodax.migration.balnSwapService`). Feature tag for errors: `'migration'`.
 
-> Don't confuse this feature (the `MigrationService` SDK module) with the v1 → v2 SDK port itself. They share the word "migration" but are independent concerns. The v1 → v2 port playbook lives at [`features/icx-bnusd-baln.md`](../../../migration-v1-to-v2/knowledge/features/icx-bnusd-baln.md).
+> Don't confuse this feature (the `MigrationService` SDK module) with the v1 → v2 SDK port itself. They share the word "migration" but are independent concerns. The v1 → v2 port playbook lives at [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
 
 ## How it works
 
@@ -177,5 +177,5 @@ try {
 
 ## Cross-references
 
-- v1 → v2 migration of this feature: [`features/icx-bnusd-baln.md`](../../../migration-v1-to-v2/knowledge/features/icx-bnusd-baln.md).
+- v1 → v2 migration of this feature: [`features/migration.md`](../../../migration-v1-to-v2/knowledge/features/migration.md).
 - Architecture (relay layer's `phase: 'destinationExecution'` for bnUSD): [`../architecture.md`](../architecture.md) § 9.