tetherto · ihsraham · Jul 30, 2026
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
 
 ---
 
+### July 28, 2026
+
+**What's New**
+- **swidge-symbiosis** ([v1.1.1](https://github.com/symbiosis-finance/wdk-protocol-swidge-symbiosis/tree/v1.1.1)): Add the community-maintained Symbiosis Swidge provider for runtime chain and token discovery, exact-input quotes, EVM, TON, and Bitcoin source execution, and settlement status polling. Execution requests a fresh provider response and proceeds internally to wallet writes after its fee checks, so applications must treat the earlier quote as indicative and validate route inputs before calling `swidge()`.
+
+---
+
 ### July 07, 2026
 
 **What's New**

diff --git a/content/docs/sdk/all-modules.mdx b/content/docs/sdk/all-modules.mdx
@@ -41,6 +41,7 @@ Swidge is the preferred interface for new protocol providers that can quote and
 |--------|----------|-------------|---------------|
 | [`wdk-protocol-swidge-orchestra`](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) | Flashnet Orchestra | Swidge provider for BTC and stablecoin routes returned by Orchestra. Treat the live [Orchestra route matrix](https://orchestration.flashnet.xyz/v1/orchestration/routes) as provider-level data and filter through package discovery before exposing routes. | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
 | [`@rhino.fi/wdk-protocol-swidge-rhinofi`](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) | Rhino.fi | Swidge routes for Rhino.fi cross-chain swap and bridge operations | [Docs](/sdk/swidge-modules/swidge-rhinofi/) |
+| [`@symbiosis-finance/wdk-protocol-swidge-symbiosis`](https://www.npmjs.com/package/@symbiosis-finance/wdk-protocol-swidge-symbiosis) | Symbiosis | Same-chain and cross-chain exact-input routes discovered and executed through the Symbiosis API | [Docs](/sdk/swidge-modules/swidge-symbiosis/) |
 
 ## Pricing Modules
 
@@ -96,3 +97,4 @@ Modules built by the WDK community. See the [Community Modules](/sdk/community-m
 | [`@morpho-org/wdk-protocol-lending-morpho-evm`](https://www.npmjs.com/package/@morpho-org/wdk-protocol-lending-morpho-evm) | EVM | Morpho Vault V2 and Morpho Blue lending integration | [Docs](/sdk/lending-modules/lending-morpho-evm/) |
 | [`wdk-protocol-swidge-orchestra`](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra) | Swidge | Flashnet Orchestra BTC and stablecoin route integration | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
 | [`@rhino.fi/wdk-protocol-swidge-rhinofi`](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) | Rhino.fi | Swidge cross-chain route integration | [Docs](/sdk/swidge-modules/swidge-rhinofi/) |
+| [`@symbiosis-finance/wdk-protocol-swidge-symbiosis`](https://www.npmjs.com/package/@symbiosis-finance/wdk-protocol-swidge-symbiosis) | Swidge | Same-chain and cross-chain exact-input routes through Symbiosis | [Docs](/sdk/swidge-modules/swidge-symbiosis/) |
diff --git a/content/docs/sdk/community-modules/index.mdx b/content/docs/sdk/community-modules/index.mdx
@@ -23,6 +23,7 @@ Tether and the WDK Team do not endorse or assume responsibility for their code,
 | [@morpho-org/wdk-protocol-lending-morpho-evm](https://www.npmjs.com/package/@morpho-org/wdk-protocol-lending-morpho-evm) ([GitHub](https://github.com/morpho-org/sdks/tree/main/packages/wdk-protocol-lending-morpho-evm)) | Lending Module | Morpho EVM lending module for vault deposits, collateral supply, borrowing, repayment, and position reads | [Docs](/sdk/lending-modules/lending-morpho-evm/) | [Morpho Association](https://morpho.org/) |
 | [wdk-protocol-swidge-orchestra](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) ([GitHub](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra)) | Swidge Module | Flashnet Orchestra Swidge provider for BTC and stablecoin routes returned by Orchestra | [Docs](/sdk/swidge-modules/swidge-orchestra/) | [Flashnet](https://github.com/flashnetxyz) |
 | [@rhino.fi/wdk-protocol-swidge-rhinofi](https://www.npmjs.com/package/@rhino.fi/wdk-protocol-swidge-rhinofi) ([GitHub](https://github.com/rhinofi/wdk-protocol-swidge-rhinofi)) | Swidge Module | Rhino.fi cross-chain swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-rhinofi/) | [Rhino.fi](https://rhino.fi/) |
+| [@symbiosis-finance/wdk-protocol-swidge-symbiosis](https://www.npmjs.com/package/@symbiosis-finance/wdk-protocol-swidge-symbiosis) ([GitHub](https://github.com/symbiosis-finance/wdk-protocol-swidge-symbiosis)) | Swidge Module | Same-chain and cross-chain exact-input routes discovered and executed through the Symbiosis API | [Docs](/sdk/swidge-modules/swidge-symbiosis/) | [Symbiosis](https://symbiosis.finance/) |
 
 ---
 

diff --git a/content/docs/sdk/swidge-modules/index.mdx b/content/docs/sdk/swidge-modules/index.mdx
@@ -27,6 +27,7 @@ Use the existing [swap modules](/sdk/swap-modules) and [bridge modules](/sdk/bri
 | Module | Provider | Routes | Documentation |
 |--------|----------|--------|---------------|
 | [`wdk-protocol-swidge-orchestra`](https://www.npmjs.com/package/wdk-protocol-swidge-orchestra) ([GitHub](https://github.com/flashnetxyz/wdk-protocol-swidge-orchestra)) | Flashnet Orchestra | BTC and stablecoin routes returned by Orchestra. Treat the live [Orchestra route matrix](https://orchestration.flashnet.xyz/v1/orchestration/routes) as provider-level data and filter through runtime discovery before exposing routes. | [Docs](/sdk/swidge-modules/swidge-orchestra/) |
+| [`@symbiosis-finance/wdk-protocol-swidge-symbiosis`](https://www.npmjs.com/package/@symbiosis-finance/wdk-protocol-swidge-symbiosis) ([GitHub](https://github.com/symbiosis-finance/wdk-protocol-swidge-symbiosis)) | Symbiosis | Same-chain and cross-chain exact-input routes discovered at runtime. | [Docs](/sdk/swidge-modules/swidge-symbiosis/) |
 
 ## Interface methods
 
@@ -209,6 +210,9 @@ Register and use protocol modules with WDK accounts
 <Card title="Orchestra" href="/sdk/swidge-modules/swidge-orchestra">
 Use the Flashnet Orchestra community Swidge provider
 </Card>
+<Card title="Symbiosis" href="/sdk/swidge-modules/swidge-symbiosis">
+Use the Symbiosis community Swidge provider
+</Card>
 <Card title="Swap Modules" href="/sdk/swap-modules">
 Maintain existing standalone swap modules
 </Card>

diff --git a/content/docs/sdk/swidge-modules/swidge-symbiosis/api-reference.mdx b/content/docs/sdk/swidge-modules/swidge-symbiosis/api-reference.mdx
@@ -0,0 +1,283 @@
+---
+title: Symbiosis Swidge API Reference
+description: API reference for @symbiosis-finance/wdk-protocol-swidge-symbiosis 1.1.1.
+docType: reference
+schemaType: APIReference
+icon: Code
+---
+
+<Callout type="warn">
+Community modules are developed and maintained independently by third-party contributors.
+
+Tether and the WDK Team do not endorse or assume responsibility for their code, security, or maintenance. Use your own judgment and proceed at your own risk.
+</Callout>
+
+## Package exports
+
+```javascript
+import SymbiosisProtocol, {
+  ApiError,
+  ConfigurationError,
+  ExactOutNotSupportedError,
+  FeeLimitExceededError,
+  ReadOnlyAccountError,
+  SymbiosisError,
+  TransactionError,
+  UnsupportedChainError,
+  UnsupportedRouteError,
+  UnsupportedTokenError,
+  ValidationError
+} from '@symbiosis-finance/wdk-protocol-swidge-symbiosis'
+```
+
+The package exports `SymbiosisProtocol` as both its default export and a named export. It also re-exports `ISwidgeProtocol` from `@tetherto/wdk-wallet/protocols`.
+
+This reference covers release [`1.1.1`](https://github.com/symbiosis-finance/wdk-protocol-swidge-symbiosis/tree/v1.1.1).
+
+## `SymbiosisProtocol`
+
+`SymbiosisProtocol` extends `SwidgeProtocol`.
+
+### Constructor
+
+```typescript
+new SymbiosisProtocol(
+  account?: IWalletAccount | IWalletAccountReadOnly,
+  config?: SymbiosisProtocolConfig
+)
+```
+
+| Account | Available operations |
+|---|---|
+| Writable account with the route's required methods | Discovery, quote, status, and supported source execution |
+| Read-only account | Discovery and status; quoting uses the account's address as the request sender |
+| `undefined` | Discovery and status; quoting requires `recipient` to supply the request sender |
+
+`chain` is optional in the constructor type, but `quoteSwidge()` and `swidge()` throw `ConfigurationError` when it is absent.
+
+### Configuration type
+
+```typescript
+type SymbiosisProtocolConfig = {
+  chain?: string | number
+  apiUrl?: string
+  defaultSlippage?: number
+  partnerAddress?: string
+  refundAddress?: string
+  skipApproval?: boolean
+  maxNetworkFeeBps?: number | bigint
+  maxProtocolFeeBps?: number | bigint
+}
+```
+
+See [Configuration](/sdk/swidge-modules/swidge-symbiosis/configuration) for defaults, validation boundaries, and execution effects.
+
+## Methods
+
+| Method | Side effects | Description |
+|---|---|---|
+| `quoteSwidge(options)` | Provider API reads only | Returns an indicative exact-input quote. |
+| `swidge(options, config?)` | Can approve and broadcast one or more source transactions | Requests a fresh execution response and submits its source route through the wallet account. |
+| `getSwidgeStatus(id, options?)` | Provider API read | Maps Symbiosis settlement state to a WDK status. |
+| `getSupportedChains()` | Provider API reads, cached | Returns provider-listed chains with WDK chain metadata. |
+| `getSupportedTokens(options?)` | Provider API read, cached | Returns provider-listed tokens, optionally filtered to one chain. |
+
+### `quoteSwidge(options)`
+
+```typescript
+quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>
+```
+
+Builds an exact-input request and calls `/v2/quote`. The method does not reserve or bind the result for `swidge()`.
+
+Package-specific errors include:
+
+- `ConfigurationError` when `chain` is missing;
+- `ValidationError` when `fromTokenAmount` is missing, a token identifier is not a string, or no account address or `recipient` supplies the request sender;
+- `ExactOutNotSupportedError` when `toTokenAmount` is present;
+- `UnsupportedChainError` or `UnsupportedTokenError` when discovery cannot resolve an identifier;
+- `ApiError` when the API returns a non-2xx response.
+
+The method can also propagate a runtime `fetch` failure or an error from `account.getAddress()`.
+
+### `swidge(options, config?)`
+
+```typescript
+swidge(
+  options: SwidgeOptions,
+  config?: SwidgeProtocolConfig
+): Promise<SwidgeResult>
+```
+
+Requires an account with `sendTransaction()`. It calls `/v2/swap`, checks the applicable fee caps, performs the route-specific approval or source-payment steps, and returns after source broadcast.
+
+The optional second argument overrides `maxNetworkFeeBps` and `maxProtocolFeeBps` for this execution.
+
+<Callout type="warn">
+`swidge()` does not consume the preceding `quoteSwidge()` response or expose its fresh `/v2/swap` response for a separate confirmation. After its fee checks, it proceeds internally to the required wallet writes.
+</Callout>
+
+### `getSwidgeStatus(id, options?)`
+
+```typescript
+getSwidgeStatus(
+  id: string,
+  options?: SwidgeStatusOptions
+): Promise<SwidgeStatusResult>
+```
+
+Pass the ID returned by `swidge()`:
+
+```text
+<sourceChainId>:<sourceTransactionHash>
+```
+
+For a bare transaction hash, pass `options.fromChain` or configure the instance source `chain`. The provider does not use other status hints.
+
+HTTP `404` is returned as `pending`, not as `ApiError`.
+
+### `getSupportedChains()`
+
+```typescript
+getSupportedChains(): Promise<SwidgeSupportedChain[]>
+```
+
+Calls the Symbiosis chain and token endpoints and maps each chain to:
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | `number` | Numeric Symbiosis chain ID |
+| `name` | `string` | Provider chain name |
+| `type` | `string` | `evm`, `utxo`, `tvm`, `tron`, or `svm` |
+| `nativeToken` | `string` | Native token symbol when present in the token catalog |
+
+### `getSupportedTokens(options?)`
+
+```typescript
+getSupportedTokens(
+  options?: SwidgeSupportedTokensOptions
+): Promise<SwidgeSupportedToken[]>
+```
+
+The chain filter is resolved as `options.toChain ?? options.fromChain`. `fromToken` and other route context do not narrow the result.
+
+| Field | Type | Description |
+|---|---|---|
+| `token` | `string` | Native-format address when present, otherwise the token symbol |
+| `chain` | `number` | Numeric Symbiosis chain ID |
+| `symbol` | `string` | Provider token symbol |
+| `decimals` | `number` | Base-unit precision |
+| `address` | `string \| undefined` | Token address when it is not the native asset |
+| `name` | `string \| undefined` | Provider token name when supplied |
+
+The response is a token catalog, not proof of pair liquidity. Request a quote for route availability.
+
+## Relevant `SwidgeOptions`
+
+| Field | Type | Provider behavior |
+|---|---|---|
+| `fromToken` | `string` | Required source token address, symbol, or native-token alias |
+| `toToken` | `string` | Required destination token address, symbol, or native-token alias |
+| `toChain` | `string \| number \| undefined` | Destination chain; defaults to the configured source chain |
+| `recipient` | `string \| undefined` | Destination recipient; defaults to the bound account address. Without an account, it also supplies the request sender |
+| `refundAddress` | `string \| undefined` | Per-call refund address; overrides the constructor default |
+| `slippage` | `number \| undefined` | Decimal slippage; overrides `defaultSlippage` |
+| `fromTokenAmount` | `number \| bigint` | Required exact input in source-token base units |
+| `toTokenAmount` | `number \| bigint` | Unsupported; throws `ExactOutNotSupportedError` |
+
+The module does not validate slippage ranges or address formats. It verifies that `fromTokenAmount` is present and converts it with `BigInt`, but it does not enforce a positive value.
+
+## Quote and result fields
+
+### `SwidgeQuote`
+
+| Field | Type | Source |
+|---|---|---|
+| `fromTokenAmount` | `bigint` | Requested exact input |
+| `toTokenAmount` | `bigint` | Provider-estimated output |
+| `toTokenAmountMin` | `bigint` | Provider minimum output after slippage |
+| `fees` | `SwidgeFee[]` | Mapped provider fee entries |
+| `estimatedDuration` | `number \| undefined` | Provider estimate in seconds |
+| `priceImpact` | `number \| undefined` | Provider percentage converted to a decimal |
+
+The provider does not map a quote expiry into `SwidgeQuote`.
+
+### `SwidgeResult`
+
+| Field | Public type | Provider behavior |
+|---|---|---|
+| `id` | `string` | `<sourceChainId>:<sourceTransactionHash>` |
+| `hash` | `string \| undefined` | Source hash; for multi-message TON execution, only the final sent message hash |
+| `fees` | `SwidgeFee[]` | Fees from the fresh execution response |
+| `transactions` | `SwidgeTransaction[] \| undefined` | Approval and recorded source hashes; status can later add destination or refund hashes |
+| `fromTokenAmount` | `bigint` | Submitted exact input |
+| `toTokenAmount` | `bigint` | Fresh provider-estimated output |
+| `toTokenAmountMin` | `bigint \| undefined` | Fresh provider minimum output |
+
+## Status mapping
+
+| Symbiosis code or response | WDK status |
+|---|---|
+| `0` | `completed` |
+| `1` | `pending` |
+| `2` | `pending` |
+| `3` | `refunded` |
+| `-1` | `pending` |
+| Unknown code | `pending` |
+| HTTP `404` | `pending` with the known source transaction |
+
+When status is `refunded`, a returned settlement transaction is labeled `refund`; otherwise it is labeled `destination`.
+
+## Fee mapping and caps
+
+| Symbiosis `fees[].provider` | WDK fee type | Cap |
+|---|---|---|
+| `symbiosis` | `protocol` | `maxProtocolFeeBps` |
+| `partner` | `affiliate` | None |
+| Any other value | `protocol` | `maxProtocolFeeBps` |
+
+Mapped fees include `amount`, `token`, `chain`, `description`, and `included: true`.
+
+The provider emits no `network` fee entry in this release, so `maxNetworkFeeBps` does not constrain the wallet transaction's chain fee. Inherited legacy `bridge()` results expose `0n` for their network `fee`; mapped protocol fees contribute to `bridgeFee`.
+
+Fee-cap fallback comparison uses decimal-normalized values when positive USD prices are unavailable. This is approximate when the fee token differs in unit value from the input token.
+
+## Error classes
+
+Every package-specific error extends `SymbiosisError`.
+
+| Error | When thrown | Useful fields |
+|---|---|---|
+| `SymbiosisError` | Base class for package-defined errors | Standard `Error` fields |
+| `ConfigurationError` | Required source `chain` configuration is missing | — |
+| `ValidationError` | A locally checked option, sender, token identifier, or status ID is invalid | — |
+| `ExactOutNotSupportedError` | `toTokenAmount` requests exact-output execution | — |
+| `UnsupportedChainError` | A chain ID or name is not in provider discovery | `identifier` |
+| `UnsupportedTokenError` | A token is not in the selected chain's token catalog | `identifier` |
+| `ReadOnlyAccountError` | Execution lacks a writable account or route-required capability | — |
+| `UnsupportedRouteError` | The API returns a source transaction type not executable through WDK in this release | `type` |
+| `FeeLimitExceededError` | A mapped `network` or `protocol` total exceeds its configured cap | `feeType`, `bps`, `cap` |
+| `TransactionError` | Approval receipt polling detects a revert or reaches its 180-second timeout | `hash` |
+| `ApiError` | The REST API returns a non-2xx response other than status lookup's special `404` handling | `status`, `response` |
+
+Runtime `fetch` failures and errors thrown by wallet account methods are propagated and are not necessarily instances of `SymbiosisError`.
+
+## Inherited compatibility methods
+
+`SymbiosisProtocol` inherits:
+
+- `swap()` and `quoteSwap()`;
+- `bridge()` and `quoteBridge()`.
+
+Those methods delegate to `swidge()` and `quoteSwidge()`. For the legacy bridge shape, the provider can resolve the destination token by matching the source token symbol on the destination chain.
+
+Prefer the Swidge methods when an application needs itemized fees, provider status, combined route semantics, or explicit destination-token selection.
+
+<Cards>
+<Card title="Usage" href="/sdk/swidge-modules/swidge-symbiosis/usage">
+Install, discover, quote, confirm, execute, and track routes.
+</Card>
+<Card title="Configuration" href="/sdk/swidge-modules/swidge-symbiosis/configuration">
+Review constructor defaults, approval behavior, fee caps, caching, and runtime constraints.
+</Card>
+</Cards>