@sodax/skills 2.0.0-rc.4

package/knowledge/wallet-sdk-core/integration/recipes/bridge-to-sdk.md

@@ -0,0 +1,145 @@
+# Recipe: Bridge to `@sodax/sdk`
+
+Pass the constructed provider to `@sodax/sdk` so the SDK can sign and submit hub/spoke transactions on the user's behalf.
+
+**Depends on:** a constructed provider (see [`setup-private-key.md`](./setup-private-key.md) or [`setup-browser-extension.md`](./setup-browser-extension.md)).
+
+---
+
+## The contract: `IXxxWalletProvider`
+
+`@sodax/sdk` consumes the chain-specific **interfaces** from `@sodax/types`, not the concrete classes. This is the indirection that keeps the SDK decoupled from `wallet-sdk-core`:
+
+```ts
+import type {
+  IEvmWalletProvider,
+  ISolanaWalletProvider,
+  ISuiWalletProvider,
+  IBitcoinWalletProvider,
+  IStellarWalletProvider,
+  IIconWalletProvider,
+  IInjectiveWalletProvider,
+  INearWalletProvider,
+  IStacksWalletProvider,
+} from '@sodax/types';
+```
+
+Each `*WalletProvider` class from `wallet-sdk-core` `implements` the matching interface. So:
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import type { IEvmWalletProvider } from '@sodax/types';
+
+const evm: IEvmWalletProvider = new EvmWalletProvider({ /* … */ });
+```
+
+In your SDK call signatures, take the **interface**, not the class:
+
+```ts
+// ✅ DO
+async function deposit(wallet: IEvmWalletProvider) { /* … */ }
+
+// ❌ DON'T — couples the function to the implementation
+async function deposit(wallet: EvmWalletProvider) { /* … */ }
+```
+
+---
+
+## Pattern: pass the provider to a `Sodax` feature service
+
+Construct the wallet provider once, instantiate the `Sodax` facade, and pass the provider as `walletProvider` to the feature method you want (swap, bridge, money market, staking, …). The `Sodax` facade owns the per-chain spoke services internally — you do **not** construct `*SpokeService` yourself.
+
+```ts
+import { Sodax } from '@sodax/sdk';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const walletProvider = new EvmWalletProvider({
+  privateKey: process.env.EVM_PK as `0x${string}`,
+  chainId: ChainKeys.SONIC_MAINNET,
+  rpcUrl: process.env.EVM_RPC,
+});
+
+const sodax = new Sodax(/* optional SodaxConfig — see @sodax/sdk docs */);
+
+// Example: supply to the money market on BSC. The wallet provider goes in
+// at the feature-method call, not at facade construction.
+const result = await sodax.moneyMarket.supply({
+  params: {
+    srcChainKey: ChainKeys.BSC_MAINNET,
+    srcAddress:  await walletProvider.getWalletAddress(),
+    token:       '0x…',
+    amount:      1_000n,
+    action:      'supply',
+  },
+  walletProvider,                           // ← the IEvmWalletProvider
+});
+```
+
+The same shape applies to `sodax.swaps.*`, `sodax.bridge.*`, `sodax.staking.*`, `sodax.migration.*`, etc. — each feature service method that needs signing takes a `walletProvider` argument typed to the chain-specific interface.
+
+> If you need the underlying spoke service for advanced read-only operations, get it via `sodax.spoke.getSpokeService(chainKey)` — but never `new EvmSpokeService(...)` yourself.
+
+For SDK-level recipes (initialise the `Sodax` facade, configure hub provider, raw-tx flows, error handling) see the [`@sodax/sdk` knowledge tree](https://github.com/icon-project/sodax-sdks/tree/main/packages/skills/knowledge/sdk/) (sibling under `@sodax/skills`).
+
+---
+
+## Pattern: React layer (typical)
+
+In a React dApp you almost never construct providers manually. `@sodax/wallet-sdk-react` returns the typed interface for you, and `@sodax/dapp-kit` wraps SDK calls into hooks:
+
+```tsx
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { useSwap } from '@sodax/dapp-kit';
+import { ChainKeys } from '@sodax/types';
+
+function SwapButton() {
+  const evm = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
+  // evm: IEvmWalletProvider | undefined
+
+  const swap = useSwap();
+
+  return (
+    <button
+      disabled={!evm}
+      onClick={() => evm && swap.mutateAsync({ /* params */, walletProvider: evm })}
+    >
+      Swap
+    </button>
+  );
+}
+```
+
+The hook narrows on `xChainId`, returns the chain-specific interface, and is `undefined` until the user is connected on that family. Refer to `@sodax/wallet-sdk-react`'s own docs for the full pattern.
+
+---
+
+## Patterns to avoid
+
+| Anti-pattern | Why bad | Replacement |
+|---|---|---|
+| Re-constructing the provider in every call site | Wastes work, can drop default config | Construct once, pass the instance around |
+| Typing functions on the concrete class (`EvmWalletProvider`) | Couples to `wallet-sdk-core` | Use the `IXxxWalletProvider` interface |
+| Casting between provider classes (`as ISolanaWalletProvider`) | Hides a chain-type mismatch | Pick the right provider for the chain at the call site |
+| Storing the provider in a long-lived Zustand / Redux store | Provider holds live SDK clients / network connections | Store the **config** (e.g. PK + chainId), construct on demand |
+
+---
+
+## Verification
+
+```bash
+# 1. Type check passes
+pnpm checkTs
+
+# 2. SDK calls type-check against the interface, not the class
+grep -rn "IEvmWalletProvider\|ISolanaWalletProvider\|IBitcoinWalletProvider" <user-src>
+# expect at least one match in your function signatures
+```
+
+---
+
+## Next steps
+
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — fine-tune the `defaults` slice for tx options.
+- [`library-exports.md`](./library-exports.md) — type-only re-exports to avoid upstream chain-SDK deps.
+- [`testing.md`](./testing.md) — mocking providers in tests.

package/knowledge/wallet-sdk-core/integration/recipes/defaults-and-overrides.md

@@ -0,0 +1,159 @@
+# Recipe: Defaults and per-call overrides
+
+Configure the `defaults` slice and understand the shallow-merge semantics shared by every provider.
+
+**Depends on:** [`setup-private-key.md`](./setup-private-key.md) or [`setup-browser-extension.md`](./setup-browser-extension.md).
+
+---
+
+## Mental model
+
+Every provider class extends `BaseWalletProvider<TDefaults>`. `defaults` is captured at construction time; per-call `options` are shallow-merged over the relevant slice at call time:
+
+```
+final  = shallowMerge(defaults[key], options)        // mergePolicy('key', options)
+       OR
+       = shallowMerge(defaults, options)              // mergeDefaults(options)
+```
+
+Two helpers, two shapes:
+
+| Helper | When the chain uses it | Example |
+|---|---|---|
+| `mergePolicy('foo', opts)` | `defaults` is **grouped per method** | EVM: `defaults.sendTransaction`, `defaults.waitForTransactionReceipt` |
+| `mergeDefaults(opts)` | `defaults` is **flat** | Bitcoin: `defaultFinalize`; Stellar: `pollInterval`, `pollTimeout` |
+
+For the helper each chain uses, see [`../features/<chain>.md`](../features/).
+
+---
+
+## Shallow, not deep
+
+Top-level keys merge; **nested objects are replaced wholesale**.
+
+```ts
+const provider = new EvmWalletProvider({
+  // …
+  defaults: {
+    sendTransaction: { gas: 3_000_000n, nonce: 0 },
+  },
+});
+
+await provider.sendTransaction(txData, { gas: 5_000_000n });
+//                                       ^^^^^^^^^^^^^^^^
+// Final policy: { gas: 5_000_000n }     ← nonce is DROPPED
+```
+
+If you need `nonce` to persist, include it in the per-call options:
+
+```ts
+await provider.sendTransaction(txData, { gas: 5_000_000n, nonce: 0 });
+```
+
+Or split the default so each tunable lives at the top level — see `src/utils/merge.ts` for the implementation. The behavior is intentional: deep merge would silently smuggle stale fields across call sites.
+
+---
+
+## `undefined` is "no opinion"
+
+The merge skips:
+
+- `undefined` **layers** entirely (no options object → use defaults verbatim).
+- `undefined` **values** inside a layer (`{ gas: undefined }` does **not** override the previous layer).
+
+```ts
+const policy: Partial<EvmSendTransactionPolicy> = { gas: undefined };
+await provider.sendTransaction(txData, policy);
+// gas falls back to defaults.sendTransaction.gas
+```
+
+This is useful when threading options through optional parameters — `undefined` reads as "use the default".
+
+---
+
+## Where to put what
+
+| Tunable | Goes where | Why |
+|---|---|---|
+| Env-level constants (RPC URL, default gas, default commitment) | `defaults` at construction | One place, captured at startup |
+| Per-call tweaks (this tx needs more gas) | per-call `options` argument | Localized, doesn't leak into other calls |
+| Anything that changes after construction (active network in PK mode) | re-construct the provider | `defaults` is frozen at startup |
+
+You **cannot** mutate `defaults` after construction — `BaseWalletProvider` captures the reference into a `protected readonly` field. Later mutations have no effect.
+
+---
+
+## Worked example: EVM with two default slices
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const provider = new EvmWalletProvider({
+  privateKey: process.env.PK as `0x${string}`,
+  chainId: ChainKeys.SONIC_MAINNET,
+  defaults: {
+    // Slice grouped by method — merged via mergePolicy('sendTransaction', …)
+    sendTransaction: { gas: 3_000_000n },
+
+    // Another method-grouped slice
+    waitForTransactionReceipt: { confirmations: 1, timeout: 60_000 },
+
+    // Constructor-time slices (private-key mode only — ignored in browser-extension mode)
+    transport: { batch: { batchSize: 10 } },
+  },
+});
+
+// Default gas: 3M.  This call bumps to 5M.
+const hash = await provider.sendTransaction(tx, { gas: 5_000_000n });
+
+// Default 1 confirmation, 60s timeout.  This call overrides both.
+const receipt = await provider.waitForTransactionReceipt(hash, {
+  confirmations: 2,
+  timeout: 30_000,
+});
+```
+
+---
+
+## Browser-extension warning
+
+In **browser-extension** mode the constructor-time slices (`transport`, `publicClient`, `walletClient` on EVM; analogous on other chains) are **ignored** — the consumer already supplied built clients, so there is nothing for the provider to configure. A one-time `console.warn` is logged.
+
+```
+[EvmWalletProvider] defaults.{transport,publicClient,walletClient} ignored in browser-extension mode.
+```
+
+This is informational, not a bug. The method-grouped slices (`sendTransaction`, `waitForTransactionReceipt`, …) still apply in both modes.
+
+---
+
+## Verification
+
+```ts
+// Assert that defaults applied — run on a testnet
+const hash = await provider.sendTransaction(tx);  // no per-call options
+// Then read the receipt and confirm gas matches your default
+```
+
+```bash
+pnpm checkTs
+```
+
+---
+
+## Common pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Expecting deep merge | A nested field was "dropped" | The whole object was replaced. Include both fields in the per-call options. |
+| Mutating `defaults` after construction | Tunable doesn't take effect | Reconstruct the provider, or pass the new value per call. |
+| Setting transport defaults in browser-extension mode | Warning logged, no effect | Move them out — they only apply in PK mode. |
+| Putting RPC URL in `defaults` | RPC URL is a top-level config field on every chain, not a `defaults` slice | Use `rpcUrl: '…'` at the config root (PK mode), or pass `publicClient` / `client` directly (browser-extension mode). |
+
+---
+
+## See also
+
+- [`../architecture.md`](../architecture.md) § `BaseWalletProvider` and the `defaults` model.
+- [`../features/`](../features/) — per-chain `*Defaults` shape and which helper each chain uses.

package/knowledge/wallet-sdk-core/integration/recipes/library-exports.md

@@ -0,0 +1,129 @@
+# Recipe: `library-exports` — re-import upstream chain types
+
+Avoid adding `viem`, `@mysten/sui`, `@solana/web3.js`, etc. as direct `package.json` deps. `@sodax/wallet-sdk-core` re-exports a curated set of types (and a handful of runtime enums) from each upstream chain SDK.
+
+**Depends on:** none — pure type-level optimisation.
+
+---
+
+## What's re-exported
+
+Source file: `src/types/library-exports.ts`. The export name is the same as upstream — only the source module changes.
+
+### Types (no runtime cost)
+
+| Chain SDK | Re-exported types |
+|---|---|
+| `viem` | `Account`, `Address`, `Chain`, `Transport`, `PublicClient`, `WalletClient`, `HttpTransportConfig`, `PublicClientConfig`, `WalletClientConfig`, `SendTransactionParameters`, `WaitForTransactionReceiptParameters`, `TransactionReceipt` |
+| `@mysten/sui/client` | `SuiTransactionBlockResponseOptions` |
+| `@mysten/sui/transactions` | `Transaction`, `TransactionArgument` |
+| `@mysten/wallet-standard` | `SuiWalletFeatures`, `WalletAccount`, `WalletWithFeatures` |
+| `@solana/web3.js` | `Commitment`, `ConnectionConfig`, `SendOptions` |
+| `@injectivelabs/networks` | `Network` |
+| `@injectivelabs/ts-types` | `ChainId`, `EvmChainId` |
+| `@injectivelabs/wallet-core` | `MsgBroadcaster` |
+| `@stacks/transactions` | `ClarityValue`, `PostConditionModeName` |
+| `@stacks/network` | `StacksNetwork` |
+| `@stacks/connect` | `StacksProvider` |
+| `near-api-js` | `KeyPairString` |
+| `@hot-labs/near-connect` | `NearConnector` |
+| `bitcoinjs-lib/src/networks.js` | `Network as BitcoinJsNetwork` |
+
+### Runtime values (also re-exported)
+
+| Source | Value | Why include the runtime |
+|---|---|---|
+| `@stellar/stellar-sdk` | `Networks` (object) | Consumers commonly read `Networks.PUBLIC` / `Networks.TESTNET` |
+| `@stacks/transactions` | `PostConditionMode` (enum) | Used as a value when building Stacks tx params |
+
+Note the file name: `library-exports` (not `library-types`). It exists precisely because the file mixes type and runtime re-exports.
+
+---
+
+## Usage
+
+```ts
+// ✅ DO — types and the two runtime enums via wallet-sdk-core
+import type {
+  WalletClient,
+  PublicClient,
+  TransactionReceipt,
+  SuiWalletFeatures,
+  WalletAccount,
+  WalletWithFeatures,
+  ConnectionConfig,
+  Network,
+  ChainId,
+  StacksNetwork,
+  StacksProvider,
+  NearConnector,
+} from '@sodax/wallet-sdk-core';
+
+import { Networks, PostConditionMode } from '@sodax/wallet-sdk-core';
+```
+
+```ts
+// ❌ DON'T — direct upstream imports for these names if you only need them as types
+import type { WalletClient } from 'viem';
+import { Networks } from '@stellar/stellar-sdk';
+```
+
+---
+
+## When to NOT use re-exports
+
+The re-export list is **curated** — only the types most consumers need. Use the upstream package directly when:
+
+- You need a type not in the re-export list (e.g. viem's `TransactionRequest`, Solana's `Keypair` value).
+- You need a **runtime value** other than `Networks` / `PostConditionMode` (e.g. viem's `createPublicClient`, `@solana/web3.js`'s `Connection`).
+- You are building a polyfill, mock, or shim around the underlying SDK.
+
+In those cases, add the upstream package to `package.json` and import normally. The re-export is an optimisation, not a hard wall.
+
+---
+
+## Why `library-exports` exists
+
+| Without it | With it |
+|---|---|
+| Consumer `package.json` lists 8+ chain SDKs explicitly | Consumer lists only `@sodax/wallet-sdk-core` + `@sodax/types` |
+| Upgrading a chain SDK touches consumer lockfiles | SODAX bumps the SDK; consumers re-install |
+| Type drift between SODAX and consumer (different `viem` minor versions) | Single source of truth — same `viem` version as SODAX uses internally |
+
+The trade-off is the curated list — uncommon types need a direct dep.
+
+---
+
+## Verification
+
+```bash
+# 1. Type check
+pnpm checkTs
+
+# 2. Confirm no direct upstream imports for re-exported types
+grep -rn "from 'viem'" <user-src> | grep -E "WalletClient|PublicClient|TransactionReceipt|SendTransactionParameters"
+grep -rn "from '@stellar/stellar-sdk'" <user-src> | grep "Networks"
+grep -rn "from '@stacks/transactions'" <user-src> | grep "PostConditionMode"
+# expect empty for all three
+
+# 3. Confirm the chain SDKs are NOT direct deps in consumer's package.json
+cat <user>/package.json | grep -E '"viem"|"@stellar/stellar-sdk"|"@stacks/transactions"|"@mysten/sui"|"@solana/web3.js"|"@injectivelabs"|"near-api-js"|"bitcoinjs-lib"'
+# expect empty unless the consumer legitimately uses a non-re-exported symbol
+```
+
+---
+
+## Common pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Importing `Networks` from `@stellar/stellar-sdk` after install | Works, but adds a direct dep | Switch to `import { Networks } from '@sodax/wallet-sdk-core'` |
+| Mixing type-only and value imports in one statement | Build size grows | `import type { … }` for types; separate value imports |
+| Expecting all viem helpers to be re-exported | `createPublicClient` is missing | Only types + 2 enums are re-exported. Other runtime helpers require direct install. |
+
+---
+
+## See also
+
+- [`../architecture.md`](../architecture.md) § `library-exports` — the upstream-SDK indirection.
+- [`../reference/public-api.md`](../reference/public-api.md) — full barrel export list.

package/knowledge/wallet-sdk-core/integration/recipes/setup-browser-extension.md

@@ -0,0 +1,137 @@
+# Recipe: Setup — browser-extension mode
+
+Construct a `*WalletProvider` from a wallet adapter that the user has already connected (MetaMask via wagmi, Phantom via wallet-adapter, Xverse via a kit, …).
+
+**Depends on:** the consumer app already obtains a chain-specific signer / client from the extension. Inside a React app, prefer `useWalletProvider` from `@sodax/wallet-sdk-react` — see § "When to skip this recipe" below.
+
+---
+
+## Pick the right chain
+
+Each chain has its own browser-extension variant. See [`../features/<chain>.md`](../features/) for exact field shapes.
+
+| Chain | Required inputs |
+|---|---|
+| EVM       | `walletClient` (viem `WalletClient<Transport, Chain, Account>`) + `publicClient` (viem `PublicClient`) |
+| Solana    | `wallet: { publicKey, signTransaction }` + `endpoint` |
+| Sui       | `client` (`SuiClient`) + `wallet` (`WalletWithFeatures<Partial<SuiWalletFeatures>>`) + `account` (`WalletAccount`) |
+| Bitcoin   | `type: 'BROWSER_EXTENSION'`, `walletsKit` (consumer-supplied adapter), `network` |
+| Stellar   | `type: 'BROWSER_EXTENSION'`, `walletsKit`, `network` |
+| ICON      | `walletAddress` (optional `hx…`) + `rpcUrl` |
+| Injective | `msgBroadcaster` |
+| NEAR      | `wallet` (`NearConnector` from `@hot-labs/near-connect`) |
+| Stacks    | `address` + optional `provider` (StacksProvider) |
+
+---
+
+## Pattern: EVM (with wagmi clients)
+
+```ts
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import type { WalletClient, PublicClient } from '@sodax/wallet-sdk-core';
+import { useWalletClient, usePublicClient } from 'wagmi';
+// …or wherever your app sources the viem clients
+
+function buildProvider(walletClient: WalletClient, publicClient: PublicClient) {
+  return new EvmWalletProvider({
+    walletClient,
+    publicClient,
+    // Optional — `defaults.sendTransaction` and `defaults.waitForTransactionReceipt`
+    // are honored. `defaults.transport / publicClient / walletClient` are IGNORED
+    // in browser-extension mode (the provider logs a one-time warning).
+    defaults: {
+      sendTransaction: { gas: 1_000_000n },
+    },
+  });
+}
+```
+
+---
+
+## Pattern: Solana (with `@solana/wallet-adapter-react`)
+
+```ts
+import { SolanaWalletProvider } from '@sodax/wallet-sdk-core';
+import { useWallet } from '@solana/wallet-adapter-react';
+
+function buildProvider() {
+  const { publicKey, signTransaction } = useWallet();
+  return new SolanaWalletProvider({
+    wallet: { publicKey, signTransaction },          // both may be null/undefined until connected
+    endpoint: 'https://api.mainnet-beta.solana.com',
+    defaults: { sendOptions: { skipPreflight: false } },
+  });
+}
+```
+
+---
+
+## Pattern: Bitcoin / Stellar (explicit `type`)
+
+```ts
+import { BitcoinWalletProvider } from '@sodax/wallet-sdk-core';
+
+const provider = new BitcoinWalletProvider({
+  type: 'BROWSER_EXTENSION',
+  walletsKit: myBitcoinAdapter,                       // implements BitcoinWalletsKit
+  network: 'MAINNET',
+});
+```
+
+The `walletsKit` is a consumer-provided adapter (Xverse / Unisat / OKX) that conforms to the `BitcoinWalletsKit` interface — see [`../features/bitcoin.md`](../features/bitcoin.md).
+
+---
+
+## When to skip this recipe
+
+You almost never construct browser-extension providers **manually** inside a React component. The right path is:
+
+```tsx
+import { useWalletProvider } from '@sodax/wallet-sdk-react';
+import { ChainKeys } from '@sodax/types';
+
+const evm = useWalletProvider({ xChainId: ChainKeys.SONIC_MAINNET });
+// evm: IEvmWalletProvider | undefined  ← already typed, already wired
+```
+
+`@sodax/wallet-sdk-react` handles the construction internally — see [`@sodax/wallet-sdk-react`: `integration/recipes/setup.md`](https://github.com/icon-project/sodax-sdks/blob/main/packages/skills/knowledge/wallet-sdk-react/integration/recipes/setup.md). Skip this recipe (the manual path) unless you are:
+
+- Building a custom non-React frontend that talks to a wallet extension directly.
+- Writing a thin wrapper around the package for a framework that doesn't have a SODAX integration yet.
+- Migrating a legacy non-React app.
+
+---
+
+## Verification
+
+```ts
+console.log(await provider.getWalletAddress());      // smoke test
+```
+
+```bash
+# Type check
+pnpm checkTs
+
+# Confirm no deep imports
+grep -rn "@sodax/wallet-sdk-core/" <user-src> | grep -v "from '@sodax/wallet-sdk-core'"
+# expect empty
+```
+
+---
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `signTransaction is not a function` (Solana) | Wallet adapter didn't provide a signer for the connected wallet | Gate construction on `signTransaction != null`. |
+| `WalletAccount is undefined` (Sui) | Adapter exposes `wallet` but not the active `account` | Read `wallet.accounts[0]` or your adapter's "current account" API before constructing. |
+| `[EvmWalletProvider] defaults.{transport,publicClient,walletClient} ignored…` | Mixed PK-mode defaults with browser-extension config | Move those defaults out — they only apply in private-key mode. |
+| Mode picked the wrong variant (TypeScript narrowing fails) | Mixed PK and browser fields | Pick **one** discriminated union variant. Don't pass both. |
+
+---
+
+## Next steps
+
+- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — hand off the provider to `@sodax/sdk` calls.
+- [`library-exports.md`](./library-exports.md) — avoid taking `viem` / `@mysten/sui` / etc. as direct deps when importing types.
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — tune `defaults`.

package/knowledge/wallet-sdk-core/integration/recipes/setup-private-key.md

@@ -0,0 +1,115 @@
+# Recipe: Setup — private-key mode
+
+Construct a `*WalletProvider` from a raw key. Use this in Node scripts, CI, tests, indexers, bots — anywhere the runtime legitimately possesses a secret.
+
+**Depends on:** none. **Do NOT** use this in a browser bundle.
+
+---
+
+## Pick the right chain
+
+Each chain has its own discriminated union. See [`../features/<chain>.md`](../features/) for exact field names.
+
+| Chain | Field that triggers PK mode | Credential shape |
+|---|---|---|
+| EVM       | `privateKey: '0x…'`                       | hex string |
+| Solana    | `privateKey: Uint8Array`                  | 64-byte secret key |
+| Sui       | `mnemonics: '…'`                          | BIP-39 phrase (no raw key option) |
+| Bitcoin   | `type: 'PRIVATE_KEY'`, `privateKey: '0x…'`| hex string + uppercase `type` |
+| Stellar   | `type: 'PRIVATE_KEY'`, `privateKey: '0x…'`| hex string + uppercase `type` |
+| ICON      | `privateKey: '0x…'`                       | hex string |
+| Injective | `secret: { privateKey } \| { mnemonics }` | nested credential object |
+| NEAR      | `privateKey: 'ed25519:…'`, `accountId`    | algorithm-prefixed string + accountId |
+| Stacks    | `privateKey: '…'`                         | string |
+
+---
+
+## Install
+
+```bash
+pnpm add @sodax/wallet-sdk-core @sodax/types
+```
+
+If you'll hand off to `@sodax/sdk`, add it too:
+
+```bash
+pnpm add @sodax/sdk
+```
+
+---
+
+## Pattern: EVM (representative)
+
+```ts
+import 'dotenv/config';
+import { EvmWalletProvider } from '@sodax/wallet-sdk-core';
+import { ChainKeys } from '@sodax/types';
+
+const PRIVATE_KEY = process.env.EVM_PRIVATE_KEY as `0x${string}`;
+if (!PRIVATE_KEY) throw new Error('EVM_PRIVATE_KEY is required');
+
+const provider = new EvmWalletProvider({
+  privateKey: PRIVATE_KEY,
+  chainId: ChainKeys.SONIC_MAINNET,                 // pick any EvmChainKey
+  rpcUrl: process.env.EVM_RPC_URL,                  // optional — defaults to viem chain's public RPC
+  defaults: {
+    sendTransaction: { gas: 3_000_000n },           // env-level fixed default
+  },
+});
+
+const address = await provider.getWalletAddress();
+console.log('Signing as:', address);
+```
+
+For other chains, swap the import and follow the field table above. Full snippets per chain live in [`../quickstart.md`](../quickstart.md).
+
+---
+
+## Keep the secret out of code
+
+| Anti-pattern | Why bad | Replacement |
+|---|---|---|
+| `privateKey: '0xabc…'` inline | Key in version control | `process.env.EVM_PRIVATE_KEY` |
+| `.env` committed to git | Same as above | `.env` in `.gitignore`, only `.env.example` committed |
+| Key in a frontend bundle | Browser users can read it | Use `setup-browser-extension.md` |
+| Key passed via CLI argv | Shows up in shell history | `dotenv-cli` + `.env` file |
+
+---
+
+## Verification
+
+```ts
+// Get-address smoke test
+console.log(await provider.getWalletAddress());
+
+// Optional: dry-run a balance read
+// (chain-specific — see ../features/<chain>.md)
+```
+
+```bash
+# 1. Type check passes
+pnpm checkTs
+
+# 2. Confirm only one provider import — barrel only
+grep -rn "from '@sodax/wallet-sdk-core" <script-dir>
+# expect zero deep paths like @sodax/wallet-sdk-core/src/...
+```
+
+---
+
+## Common errors
+
+| Error | Cause | Fix |
+|---|---|---|
+| `Invalid EVM wallet config` | Mixed PK and browser-extension fields in one object | Pick **one** variant. Don't pass both `privateKey` and `walletClient`. |
+| TS2322: `'string'` is not assignable to `` `0x${string}` `` | Missing hex prefix or wrong type | Read from env with `as \`0x${string}\`` after a runtime check. |
+| TS: `Property 'secret' is missing` (Injective) | Used `privateKey` at top level | Wrap in `{ secret: { privateKey } }` or `{ secret: { mnemonics } }`. See [`../features/injective.md`](../features/injective.md). |
+| `Cannot find module 'viem/chains'` for unknown chain | Passed an EVM chain key not in `getEvmViemChain` | Use a `ChainKeys.*_MAINNET` constant — the function is exhaustive. |
+
+---
+
+## Next steps
+
+- [`bridge-to-sdk.md`](./bridge-to-sdk.md) — pass the provider to `@sodax/sdk` for swap / lend / bridge / stake.
+- [`defaults-and-overrides.md`](./defaults-and-overrides.md) — tune the `defaults` slice.
+- [`sign-and-broadcast.md`](./sign-and-broadcast.md) — chain-by-chain raw-tx flow.