Document routingAndLiquidityOptions for SDK and widget

integration-examples.md

@@ -43,7 +43,7 @@ Full-featured web UI demonstrating swap, bridge, Compact deposits, balance queri
 | `src/config/web3.ts` | Token/chain discovery from SDK graphs |
 | `src/config/api.ts` | `VITE_API_BASE_URL` helper |
 | `src/hooks/useAllocatorAPI.ts` | Health check, allocator address |
-| `src/pages/BalancePage.tsx` | Full swap flow: quote → solve → status |
+| `src/pages/BalancePage.tsx` | Full swap flow: routing preset picker, quote → solve → status |
 | `src/components/UserBalancesList.tsx` | `getDepositedBalances` |
 | `src/components/WalletWithdrawDialog.tsx` | Forced withdrawal flow |
 

integration-guides/sdk-integration-guide.md

@@ -55,8 +55,8 @@ Full chain and token tables: [Supported Chains & Tokens](../supported-chains-and
 ```
 → getHealthCheck()
 → getTaskData({ taskType, intentData })
-→ getIntentQuote({ sponsorAddress, taskTypeString, intentData })
-→ solveIntent({ ...params, quoteResult, onExecutionStatus })
+→ getIntentQuote({ sponsorAddress, taskTypeString, intentData, routingAndLiquidityOptions? })
+→ solveIntent({ ...params, quoteResult, routingAndLiquidityOptions?, onExecutionStatus })
 → getIntentStatus(userAddress, nonce)
 ```
 
@@ -135,6 +135,36 @@ if (nonce) {
 
 See [epoch-integration-demo](../integration-examples.md#epoch-integration-demo) for a runnable Node.js script.
 
+### Routing & liquidity options (optional)
+
+Use `routingAndLiquidityOptions` when you want to control **how** the swap is filled — single-transaction filler liquidity (one user signature, seamless end-to-end execution including protocol interactions) vs multi-transaction external routing vs best-of-all.
+
+```typescript
+import type { RoutingAndLiquidityOptions } from "@epoch-protocol/epoch-intents-sdk";
+
+const routingAndLiquidityOptions: RoutingAndLiquidityOptions = {
+  preset: "filler-single-transaction",
+};
+
+const quoteResult = await sdk.getIntentQuote({
+  sponsorAddress: account.address,
+  taskTypeString,
+  intentData,
+  routingAndLiquidityOptions,
+});
+
+await sdk.solveIntent({
+  isNative: false,
+  sponsorAddress: account.address,
+  taskTypeString,
+  intentData,
+  quoteResult,
+  routingAndLiquidityOptions, // same as quote
+});
+```
+
+Presets: `any` (default), `filler-single-transaction` (one transaction, seamless end-to-end execution for the user — protocol interactions handled by the filler), `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). See [SDK Reference](./sdk-reference.md#getintentquoteparams).
+
 ***
 
 ## React + wagmi Pattern (from compact-demo-epoch)

integration-guides/sdk-reference.md

@@ -59,9 +59,28 @@ getIntentQuote(params: {
   taskTypeString: string;
   intentData: unknown;
   isNative?: boolean;
+  routingAndLiquidityOptions?: RoutingAndLiquidityOptions;
 }): Promise<IntentQuoteResult>
 ```
 
+**`RoutingAndLiquidityOptions`** (optional) — controls which solver liquidity paths SIO may quote. Mapped server-side to `constraint.preferredSolvers`. Use the **same** value in `getIntentQuote` and `solveIntent`.
+
+| Preset | UX | Behavior |
+|--------|-----|----------|
+| `{ preset: "any" }` | Best quote (default) | All registered solvers |
+| `{ preset: "filler-single-transaction" }` | One user transaction; seamless end-to-end execution | Epoch filler treasury only — protocol interactions bundled behind a single signature |
+| `{ preset: "external-multi-transactions" }` | Multi-transaction flow | External aggregators only |
+| `{ preset: "custom"; solvers: [\`0x…\`] }` | Pin specific solver(s) | Explicit solver address(es) |
+
+```typescript
+await sdk.getIntentQuote({
+  sponsorAddress,
+  taskTypeString,
+  intentData,
+  routingAndLiquidityOptions: { preset: "filler-single-transaction" },
+});
+```
+
 **`IntentQuoteResult` fields:**
 
 | Field | Type | Description |
@@ -88,6 +107,7 @@ solveIntent(params: {
   taskTypeString: string;
   intentData: unknown;
   quoteResult?: IntentQuoteResult;  // optional; fetched internally if omitted
+  routingAndLiquidityOptions?: RoutingAndLiquidityOptions;
   onExecutionStatus?: (status: TransactionExecutionStatus) => void;
   collateralType?: CollateralType;  // EVM | Miden — partner flows
 }): Promise<unknown>

integration-guides/skills.md

@@ -86,8 +86,8 @@ Full chain/token tables and API details: [reference.md](reference.md)
 ```
 GET /health
   → getTaskData({ taskType, intentData })
-  → getIntentQuote({ sponsorAddress, taskTypeString, intentData })
-  → solveIntent({ ...params, quoteResult, onExecutionStatus })
+  → getIntentQuote({ sponsorAddress, taskTypeString, intentData, routingAndLiquidityOptions? })
+  → solveIntent({ ...params, quoteResult, routingAndLiquidityOptions?, onExecutionStatus })
   → getIntentStatus(userAddress, nonce)
 ```
 

integration-guides/swap-and-bridge.md

@@ -99,6 +99,36 @@ Always require explicit user confirmation before calling `solveIntent`.
 
 ***
 
+## Routing & liquidity options
+
+Optional `routingAndLiquidityOptions` lets integrators choose **how** the swap is filled:
+
+| Preset | When to use |
+|--------|-------------|
+| `any` | Default — best quote across all solvers |
+| `filler-single-transaction` | Prefer Epoch filler liquidity — the user signs **one** transaction for seamless end-to-end execution (protocol interactions are handled behind the scenes) |
+| `external-multi-transactions` | External aggregators only (multi-step signing) |
+| `custom` | Pin specific solver address(es) |
+
+Pass the **same** options to `getIntentQuote` and `solveIntent`:
+
+```typescript
+const routingAndLiquidityOptions = { preset: "filler-single-transaction" as const };
+
+const quote = await sdk.getIntentQuote({
+  sponsorAddress,
+  taskTypeString,
+  intentData,
+  routingAndLiquidityOptions,
+});
+
+await sdk.solveIntent({ ...params, quoteResult: quote, routingAndLiquidityOptions });
+```
+
+See [SDK Reference](./sdk-reference.md#getintentquoteparams).
+
+***
+
 ## Chain and token selection
 
 * Source chain: where the user's wallet is connected and input tokens exist.

integration-guides/widget-integration.md

@@ -240,6 +240,20 @@ api={{ baseUrl: 'https://allocator.example.com', positionsBaseUrl: 'https://posi
 
 By default the destination is **pinned**. Set `lockDestinationToken={false}` to let the user re-pick it. Scope the source side with `sourceChainIds`, `defaultSourceChainId`, `defaultSourceTokenAddress`, `sourceTokenFilter`.
 
+**Routing & liquidity** — restrict which solver paths are quoted (pay, swap, and earn):
+
+```tsx
+<EpochIntentWidget
+  isOpen={open} onClose={close}
+  api={{ baseUrl }}
+  mode="pay"
+  routingAndLiquidityOptions={{ preset: "filler-single-transaction" }}
+  intent={{ /* … */ }}
+/>
+```
+
+Presets: `any`, `filler-single-transaction` (one user transaction with seamless end-to-end execution — protocol interactions handled behind the scenes), `external-multi-transactions`, `custom` (with `solvers: [\`0x…\`]`). Use the same value for quote and submit — the widget forwards it to the SDK automatically.
+
 ### Swap
 
 `mode="swap"` — classic exchange UX; the user picks **both** sides. Provide an initial destination intent (`lockDestinationToken` is forced off internally so the user can always change what they receive):