tetherto · ihsraham · May 19, 2026 · May 19, 2026 · May 19, 2026 · May 19, 2026
diff --git a/README.md b/README.md
@@ -1,29 +1,80 @@
-# WDK docs
+# WDK Docs
 
 Official documentation for the Wallet Development Kit (WDK) by Tether.
 
 Live at: [docs.wdk.tether.io](https://docs.wdk.tether.io)
 
-## Architecture
+## Stack
 
-WDK docs website is a static website generated via SSG functionality from a Next.js+[Fumadocs](https://fumadocs.dev) application.
+The docs site is a static Next.js application built with [Fumadocs](https://fumadocs.dev).
 
+- Docs content lives in `content/docs/**/*.mdx`.
+- Sidebar navigation is defined in `src/lib/custom-tree.ts`.
+- Generated Fumadocs artifacts live under `.source/` and should not be edited directly.
+- Generated search output at `public/api/search.json` is created by dev/build scripts and should not be committed unless the project intentionally starts tracking it.
 
-## Development
+## Prerequisites
 
-`@tetherto/docs-seo-*` is installed from GitHub Packages. Add a package-read
-token to `.env.local`, then export it before installing dependencies:
+- Node.js 22 or newer.
+- npm.
+- A GitHub token with `read:packages` access for installing `@tetherto/docs-seo-*` from GitHub Packages.
+
+## Setup
+
+Copy the local environment template and add your package-read token:
 
 ```bash
 cp .env.example .env.local
-set -a && . ./.env.local && set +a
 ```
 
+Set `GITHUB_TOKEN` in `.env.local`, then export it before installing dependencies:
+
 ```bash
+set -a && . ./.env.local && set +a
 npm install
+```
+
+## Local Preview
+
+Start the local docs server:
+
+```bash
 npm run dev
 ```
 
+The dev server runs on [http://localhost:3001](http://localhost:3001). The command generates the local search index first, then starts Next.js with Fumadocs.
+
+Useful smoke-test routes:
+
+- [http://localhost:3001/](http://localhost:3001/)
+- [http://localhost:3001/overview/changelog/](http://localhost:3001/overview/changelog/)
+- [http://localhost:3001/sdk/all-modules/](http://localhost:3001/sdk/all-modules/)
+- [http://localhost:3001/sdk/swidge-modules/](http://localhost:3001/sdk/swidge-modules/)
+- [http://localhost:3001/sdk/core-module/guides/protocol-integration/](http://localhost:3001/sdk/core-module/guides/protocol-integration/)
+
+If port `3001` is already in use, stop the other process or run Next directly with another port:
+
+```bash
+DOCS_SEO_QUIET_GENERATED=1 NODE_OPTIONS='--import tsx/esm' npx next dev --turbo -p 3002
+```
+
+## Validation
+
+Run these checks before opening or updating a PR:
+
+```bash
+git diff --check
+npm run check:meta
+LINK_CHECK_EXTERNAL=false npm run check:links
+npm run build
+```
+
+Use the external link checker when network checks are required:
+
+```bash
+npm run check:links
+```
+
 ## Build
 
 ```bash
@@ -56,10 +107,10 @@ Important environment variables:
 
 ```bash
 # Comprehensive markdown-level link checker (internal + external + anchors + assets)
-node scripts/check-links.mjs
+npm run check:links
 
 # Internal-only (fast, no network)
-LINK_CHECK_EXTERNAL=false node scripts/check-links.mjs
+LINK_CHECK_EXTERNAL=false npm run check:links
 ```
 
 ## License

diff --git a/content/docs/ai/agent-skills.mdx b/content/docs/ai/agent-skills.mdx
@@ -16,7 +16,7 @@ WDK provides agent skills: structured instruction sets that teach AI agents how
 
 An agent skill is a structured set of instructions and reference documentation that teaches an AI agent to use a specific tool or SDK. Skills follow the [AgentSkills specification](https://agentskills.io/specification). Each skill is a `SKILL.md` file with frontmatter metadata and detailed instructions that any compatible agent can load and execute.
 
-WDK publishes a skill that covers the full SDK surface: wallet modules, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md).
+WDK publishes a skill that covers the full SDK surface: wallet modules, swidge, swap, bridge, lending, fiat on/off-ramps, and the indexer. When an agent loads the skill, it learns WDK's APIs so you don't need blockchain expertise to get started. You can view the full skill file on [GitHub](https://github.com/tetherto/wdk-docs/blob/main/skills/wdk/SKILL.md).
 
 ## Capabilities
 

diff --git a/content/docs/overview/changelog.mdx b/content/docs/overview/changelog.mdx
@@ -10,6 +10,13 @@ Stay up to date with the latest improvements, new features, and bug fixes across
 
 ---
 
+### May 19, 2026
+
+**What's New**
+- **[Swidge Protocol Interface](../sdk/swidge-modules)**: New page covering WDK's shared route interface for swap-only, bridge-only, and combined swap and bridge providers, including `quoteSwidge()`, `executeSwidge()`, `getSwidgeStatus()`, route options, result fields, status values, fee handling, and migration guidance for the existing standalone swap and bridge interfaces.
+
+---
+
 ### April 22, 2026
 
 **Fixes**

diff --git a/content/docs/sdk/all-modules.mdx b/content/docs/sdk/all-modules.mdx
@@ -1,6 +1,6 @@
 ---
 title: All Modules
-description: Complete list of all available WDK modules including wallet, swap, bridge, lending, and fiat modules.
+description: Complete list of all available WDK modules including wallet, swidge, swap, bridge, lending, and fiat modules.
 docType: reference
 schemaType: TechArticle
 ---
@@ -31,6 +31,12 @@ Wallet modules provide blockchain-specific wallet functionality for managing add
 | [`@tetherto/wdk-wallet-solana`](https://github.com/tetherto/wdk-wallet-solana) | Solana | Solana blockchain wallet | [Docs](./wallet-modules/wallet-solana/) |
 | [`@tetherto/wdk-wallet-spark`](https://github.com/tetherto/wdk-wallet-spark) | Spark | Spark/Lightning Bitcoin L2 wallet | [Docs](./wallet-modules/wallet-spark/) |
 
+## Swidge Modules
+
+Swidge modules provide one interface for providers that can quote and execute swap-only, bridge-only, or combined swap and bridge routes.
+
+No released swidge provider module is listed yet. See the [swidge protocol interface](./swidge-modules/) for the shared API shape provider modules should implement.
+
 ## Swap Modules
 
 DEX swap functionality for token exchanges.

diff --git a/content/docs/sdk/bridge-modules/index.mdx b/content/docs/sdk/bridge-modules/index.mdx
@@ -7,6 +7,10 @@ schemaType: TechArticle
 
 The Wallet Development Kit (WDK) provides a set of modules that support bridging between different blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations.
 
+<Callout type="info">
+WDK is introducing the [swidge interface](/sdk/swidge-modules) for providers that can support swap-only, bridge-only, or combined swap and bridge routes through one route interface. Existing bridge modules remain supported, but the standalone bridge interface is expected to be deprecated in a future release once swidge provider modules are available.
+</Callout>
+
 ## Bridge Protocol Modules
 
 Cross-chain bridge functionality for token transfers between blockchains:
@@ -27,4 +31,4 @@ To get started with WDK modules, follow these steps:
 You can also:
 
 - Learn about key concepts like [Account Abstraction](../../resources/concepts#account-abstraction) and other important definitions
-- Use one of our ready-to-use examples to be production ready
+- Use one of our ready-to-use examples to be production ready
diff --git a/content/docs/sdk/core-module/api-reference.mdx b/content/docs/sdk/core-module/api-reference.mdx
@@ -497,8 +497,23 @@ interface ILendingProtocol {
   borrow(options: LendingOptions): Promise<LendingResult>;
   repay(options: LendingOptions): Promise<LendingResult>;
 }
+
+// Swidge Protocol
+interface ISwidgeProtocol {
+  quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>;
+  executeSwidge(
+    quote: SwidgeQuote,
+    config?: SwidgeProtocolConfig
+  ): Promise<SwidgeResult>;
+  getSwidgeStatus(
+    id: string,
+    options?: SwidgeStatusOptions
+  ): Promise<SwidgeStatusResult>;
+}
 ```
 
+`ISwidgeProtocol` is the shared interface for providers that can execute swap-only, bridge-only, or combined swap and bridge routes. See [Swidge Protocol Interface](/sdk/swidge-modules) for the full option, quote, result, fee, and status shapes.
+
 ***
 
 ## Next Steps

diff --git a/content/docs/sdk/core-module/guides/protocol-integration.mdx b/content/docs/sdk/core-module/guides/protocol-integration.mdx
@@ -1,11 +1,11 @@
 ---
 title: Integrate Protocols
-description: Learn how to use Swaps, Bridges, and Lending protocols.
+description: Learn how to use Swidge, Swap, Bridge, and Lending protocols.
 docType: how-to
 schemaType: TechArticle
 ---
 
-The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like [token swapping](#swapping-tokens), [cross-chain bridging](#bridging-assets), and lending, all through a unified interface.
+The WDK Core module supports registering external protocols. This allows you to extend the basic wallet functionality with advanced features like [swidge routes](/sdk/swidge-modules), [token swapping](#swapping-tokens), [cross-chain bridging](#bridging-assets), and lending.
 
 ## Register Protocols
 
@@ -54,7 +54,35 @@ const wdk = new WDK(seedPhrase)
 
 ## Use Protocols
 
-Once [registered](#register-protocols), you can access the protocol instance using the specific getter methods: `getSwapProtocol`, `getBridgeProtocol`, or `getLendingProtocol`.
+Once [registered](#register-protocols), you can access the protocol instance using the specific getter methods, such as `getSwapProtocol`, `getBridgeProtocol`, `getLendingProtocol`, or `getFiatProtocol`.
+
+### Swidge Routes
+
+Use a swidge provider module when one provider can quote and execute swap-only, bridge-only, or combined swap and bridge routes through the same interface. The shared swidge interface quotes with `quoteSwidge()`, executes with `executeSwidge()`, and tracks asynchronous settlement with `getSwidgeStatus()`. The example below assumes `swidge` is an instance of a concrete provider module that implements the shared interface.
+
+```typescript title="Swidge route flow"
+const quote = await swidge.quoteSwidge({
+  fromToken: '0xSourceToken...',
+  toToken: '0xDestinationToken...',
+  toChain: 'arbitrum',
+  recipient: '0xRecipient...',
+  fromTokenAmount: 1000000n,
+  slippage: 0.01
+})
+
+const result = await swidge.executeSwidge(quote, {
+  swidgeMaxFee: 200000000000000n
+})
+
+const status = await swidge.getSwidgeStatus(result.id, {
+  toChain: 'arbitrum',
+  providerData: result.providerData
+})
+```
+
+<Callout type="info">
+Existing swap and bridge modules keep their current accessors until swidge provider modules ship. See the [swidge protocol interface](/sdk/swidge-modules) for the shared API shape.
+</Callout>
 
 ### Swapping Tokens
 

diff --git a/content/docs/sdk/core-module/usage.mdx b/content/docs/sdk/core-module/usage.mdx
@@ -22,7 +22,7 @@ Retrieve accounts and check balances.
 Transfer native tokens.
 </Card>
 <Card title="Integrate Protocols" href="/sdk/core-module/guides/protocol-integration">
-Use Swap, Bridge, and Lending protocols.
+Use Swidge, Swap, Bridge, and Lending protocols.
 </Card>
 <Card title="Configure Middleware" href="/sdk/core-module/guides/middleware">
 Add logging and failover protection.

diff --git a/content/docs/sdk/get-started.mdx b/content/docs/sdk/get-started.mdx
@@ -14,7 +14,7 @@ It is built on some core principles: **self-custodial and stateless** (private k
 
 * **Multi-Chain Support**: Bitcoin, Ethereum, TON, TRON, Solana, Spark, and more
 * **Account Abstraction**: Gasless transactions on supported chains
-* **DeFi Integration**: Plug-in support for swaps, bridges, and lending protocols
+* **DeFi Integration**: Plug-in support for swidge routes, swaps, bridges, and lending protocols
 * **Extensible Design**: Add custom modules for new blockchains or protocols
 
 ***
@@ -32,7 +32,7 @@ New functionality is added through modules rather than modifying core code. Also
 
 #### Module Types
 
-WDK modules are organized into five main categories, each serving a specific purpose in the blockchain application stack:
+WDK modules are organized into six main categories, each serving a specific purpose in the blockchain application stack:
 
 <Cards>
 <Card title="Core" href="/sdk/core-module">
@@ -41,6 +41,9 @@ Main orchestrator and shared utilities
 <Card title="Wallet" href="/sdk/wallet-modules">
 Blockchain-specific wallet operations
 </Card>
+<Card title="Swidge" href="/sdk/swidge-modules">
+Swap-only, bridge-only, or combined asset routes
+</Card>
 <Card title="Swap" href="/sdk/swap-modules">
 Token swapping across DEXs
 </Card>

diff --git a/content/docs/sdk/swap-modules/index.mdx b/content/docs/sdk/swap-modules/index.mdx
@@ -7,6 +7,10 @@ schemaType: TechArticle
 
 The Swap Development Kit (WDK) provides a set of modules that support swap on top of multiple blockchain networks. All modules share a common interface, ensuring consistent behavior across different blockchain implementations.
 
+<Callout type="info">
+WDK is introducing the [swidge interface](/sdk/swidge-modules) for providers that can support swap-only, bridge-only, or combined swap and bridge routes through one route interface. Existing swap modules remain supported, but the standalone swap interface is expected to be deprecated in a future release once swidge provider modules are available.
+</Callout>
+
 ## Swap Protocol Modules
 
 DeFi swap functionality for token exchanges across different DEXs: