Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion content/docs/overview/changelog.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -90,7 +90,7 @@ Stay up to date with the latest improvements, new features, and bug fixes across
### June 11, 2026

**What's New**
- **swidge-lifi** ([v0.2.0](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi/v/0.2.0)): Add generated TypeScript declarations, request timeouts and retries, typed LI.FI error classes, input and transaction validation, optional trusted-contract checks, and fee-cap handling for LI.FI swidge routes.
- **@lifi/wdk-protocol-swidge-lifi** ([v0.5.1](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi/v/0.5.1)): Add generated TypeScript declarations, request timeouts and retries, typed LI.FI error classes, input and transaction validation, optional trusted-contract checks, fee-cap handling, an optional `minAmountOut` execution guard for quote-first flows, opt-in gasless route filtering (`NATIVE_VALUE_BRIDGE_DENY_LIST` and `allowNativeValue`), and per-fee-token chain attribution for LI.FI swidge routes.

---

Expand Down
4 changes: 2 additions & 2 deletions content/docs/sdk/all-modules.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -38,7 +38,7 @@ Swidge is the preferred interface for new protocol providers that can quote and

| Module | Provider | Description | Documentation |
|--------|----------|-------------|---------------|
| [`@kenny_io/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) | LI.FI | Swidge routes for LI.FI swap, bridge, and combined swap-plus-bridge operations | [Docs](/sdk/swidge-modules/swidge-lifi/) |
| [`@lifi/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) | LI.FI | Swidge routes for LI.FI swap, bridge, and combined swap-plus-bridge operations | [Docs](/sdk/swidge-modules/swidge-lifi/) |

## Pricing Modules

Expand Down Expand Up @@ -90,4 +90,4 @@ Modules built by the WDK community. See the [Community Modules](/sdk/community-m
|--------|------------|-------------|---------------|
| [`@utexo/wdk-wallet-rgb`](https://github.com/UTEXO-Protocol/wdk-wallet-rgb) | Bitcoin (RGB) | RGB protocol wallet integration | [Docs](/sdk/community-modules/wdk-wallet-rgb/) |
| [`@base58-io/wdk-wallet-cosmos`](https://github.com/base58-io/wdk-wallet-cosmos) | Cosmos | Cosmos-compatible wallet integration | [Docs](/sdk/community-modules/wdk-wallet-cosmos/) |
| [`@kenny_io/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) | LI.FI | Swidge swap and bridge route integration | [Docs](/sdk/swidge-modules/swidge-lifi/) |
| [`@lifi/wdk-protocol-swidge-lifi`](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) | LI.FI | Swidge swap and bridge route integration | [Docs](/sdk/swidge-modules/swidge-lifi/) |
2 changes: 1 addition & 1 deletion content/docs/sdk/community-modules/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ Tether and the WDK Team do not endorse or assume responsibility for their code,
| [@arkade-os/wdk](https://www.npmjs.com/package/@arkade-os/wdk) ([GitHub](https://github.com/arkade-os/arkade-wdk)) | Wallet Module | Bitcoin wallet module built on the Arkade SDK with Arkade addresses, boarding addresses, BIP21/LNURL/Lightning send routing, and optional Boltz swaps | [README](https://github.com/arkade-os/arkade-wdk#readme) | [Arkade](https://github.com/arkade-os) |
| [@base58-io/wdk-wallet-cosmos](https://www.npmjs.com/package/@base58-io/wdk-wallet-cosmos) ([GitHub](https://github.com/base58-io/wdk-wallet-cosmos)) | Wallet Module | Wallet module for Cosmos-compatible blockchains | [Docs](/sdk/community-modules/wdk-wallet-cosmos/) | [Base58](https://base58.io/) |
| [@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/) |
| [@kenny_io/wdk-protocol-swidge-lifi](https://www.npmjs.com/package/@kenny_io/wdk-protocol-swidge-lifi) ([GitHub](https://github.com/kenny-io/wdk-lifi-swidge-protocol)) | Swidge Module | LI.FI swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-lifi/) | [Kenny](https://github.com/kenny-io) |
| [@lifi/wdk-protocol-swidge-lifi](https://www.npmjs.com/package/@lifi/wdk-protocol-swidge-lifi) ([GitHub](https://github.com/lifinance/wdk-lifi-swidge-protocol)) | Swidge Module | LI.FI swap and bridge routes through the WDK swidge interface | [Docs](/sdk/swidge-modules/swidge-lifi/) | [LI.FI](https://li.fi/) |

---

Expand Down
14 changes: 10 additions & 4 deletions content/docs/sdk/swidge-modules/swidge-lifi/api-reference.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: LI.FI Swidge API Reference
description: API reference for @kenny_io/wdk-protocol-swidge-lifi.
description: API reference for @lifi/wdk-protocol-swidge-lifi.
docType: reference
schemaType: APIReference
icon: Code
Expand All @@ -13,7 +13,7 @@ icon: Code
```javascript
import {
LifiSwidgeProtocol
} from '@kenny_io/wdk-protocol-swidge-lifi'
} from '@lifi/wdk-protocol-swidge-lifi'

const swidge = new LifiSwidgeProtocol(account, config)
```
Expand All @@ -29,7 +29,9 @@ new LifiSwidgeProtocol(account?, config?)
| `WalletAccountEvm` | Discovery, quote, status, and execution. |
| `WalletAccountEvmErc4337` | Discovery, quote, status, and execution through a smart account. |
| `WalletAccountReadOnlyEvm` | Discovery, quote, and status. |
| `undefined` | Discovery and account-independent quote setup. |
| `undefined` | Chain and token discovery only. |

Use `WalletAccountReadOnlyEvm` for quote-only flows that should not sign transactions. No-account mode cannot provide the source address required by LI.FI quotes.

## Methods

Expand Down Expand Up @@ -60,7 +62,9 @@ swidge(

Executes through the bound writable account. The module sends required approval transactions before the route transaction where needed.

Throws before execution when validation fails, a configured fee cap is exceeded, or `trustedContracts` rejects the quote target or approval address.
For quote-first flows, pass the `minAmountOut` field in `options`: set it to the `toTokenAmountMin` from a previously displayed `quoteSwidge()` result, and `swidge()` throws before any approval or transaction is sent if the fresh execution quote's minimum output falls below it. `minAmountOut` is not forwarded to LI.FI, and `quoteSwidge()` ignores it.

Throws before execution when validation fails, a fee cap is exceeded, the quote falls below `minAmountOut`, `allowNativeValue: false` and the quote requires native value, or `trustedContracts` rejects the quote target or approval address.

### `getSwidgeStatus(id, options?)`

Expand Down Expand Up @@ -92,6 +96,8 @@ type LifiSwidgeProtocolConfig = {
order?: LifiRouteOrder
allowBridges?: string[]
denyBridges?: string[]
allowDestinationCall?: boolean
allowNativeValue?: boolean
timeout?: number
retries?: number
retryDelay?: number
Expand Down
32 changes: 29 additions & 3 deletions content/docs/sdk/swidge-modules/swidge-lifi/configuration.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: LI.FI Swidge Configuration
description: Configuration options for @kenny_io/wdk-protocol-swidge-lifi.
description: Configuration options for @lifi/wdk-protocol-swidge-lifi.
docType: reference
schemaType: TechArticle
icon: Settings
Expand All @@ -10,7 +10,7 @@ Configure `LifiSwidgeProtocol` with a WDK EVM account when you need execution, o

```javascript
import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm'
import { LifiSwidgeProtocol } from '@kenny_io/wdk-protocol-swidge-lifi'
import { LifiSwidgeProtocol } from '@lifi/wdk-protocol-swidge-lifi'

const account = new WalletAccountEvm(seedPhrase, "0'/0/0", {
provider: 'https://mainnet.infura.io/v3/YOUR_KEY'
Expand Down Expand Up @@ -44,7 +44,9 @@ new LifiSwidgeProtocol(account?, config?)
| `apiKey` | `string` | LI.FI API key for higher rate limits. Keep it server-side. |
| `order` | `'RECOMMENDED' \| 'FASTEST' \| 'CHEAPEST'` | Route selection strategy. Defaults to `RECOMMENDED`. |
| `allowBridges` | `string[]` | Bridge protocol allowlist, for example `['stargate']`. |
| `denyBridges` | `string[]` | Bridge protocol denylist, for example `['across']`. |
| `denyBridges` | `string[]` | Bridge protocol denylist, for example `['across']`. When omitted, no bridge filter is sent and LI.FI considers all bridges. For gasless integrations, pass the exported `NATIVE_VALUE_BRIDGE_DENY_LIST` to exclude bridges that require native token value. |
| `allowDestinationCall` | `boolean` | Allows LI.FI routes that execute a destination-chain call, such as a destination-chain swap. Forwarded only when set explicitly; when omitted, LI.FI's own default (`true`) applies. Set `false` to filter out routes that may leave the user with an intermediary token if the destination call fails. |
| `allowNativeValue` | `boolean` | Whether `swidge()` may execute quotes whose transaction requires native token value (`transactionRequest.value > 0`). Defaults to `true`. Set `false` for gasless setups (for example ERC-4337 with a paymaster): such quotes are rejected before any approval is sent. |
| `maxNetworkFeeBps` | `number \| bigint` | Rejects execution when network fees exceed this many basis points of the input amount. |
| `maxProtocolFeeBps` | `number \| bigint` | Rejects execution when protocol fees exceed this many basis points of the input amount. |
| `timeout` | `number` | Per-request timeout in milliseconds. Defaults to `30000`. |
Expand All @@ -63,6 +65,30 @@ await swidge.swidge(options, {
})
```

## Route Filtering

By default the module applies no extra route filtering: `denyBridges` is not set, `allowDestinationCall` is not forwarded (LI.FI's server-side default of `true` applies), and quotes that require native token value execute as-is. This gives the widest route coverage and matches LI.FI SDK behavior.

For gasless integrations — for example ERC-4337 where a paymaster covers source-chain gas but the LI.FI route transaction itself must not require separate native token value — opt in explicitly:

```javascript
import {
LifiSwidgeProtocol,
NATIVE_VALUE_BRIDGE_DENY_LIST
} from '@lifi/wdk-protocol-swidge-lifi'

const swidge = new LifiSwidgeProtocol(account, {
denyBridges: NATIVE_VALUE_BRIDGE_DENY_LIST, // filter native-value bridges at quote time
allowNativeValue: false // reject any quote whose tx still needs native value
})
```

`NATIVE_VALUE_BRIDGE_DENY_LIST` is the maintained list of bridges known to require native token value in the source transaction. `denyBridges` replaces (does not append to) any default, so `denyBridges: ['across']` denies only `across`.

Set `allowDestinationCall: false` to exclude routes that require a destination-chain call, such as a swap after bridging, which can leave the user holding an intermediary token if the destination call fails.

With `allowNativeValue: false`, execution rejects any quote whose transaction request requires native token value before sending approvals or the route transaction, even if a native-value bridge was not filtered out at quote time.

## Contract Validation

The module always validates returned transaction data before forwarding it to the wallet. Enable `trustedContracts` when the integration also needs an allowlist check against LI.FI Diamond deployments and Permit2.
Expand Down
9 changes: 6 additions & 3 deletions content/docs/sdk/swidge-modules/swidge-lifi/index.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: LI.FI Swidge Overview
description: Overview of the @kenny_io/wdk-protocol-swidge-lifi module for LI.FI swap and bridge routes.
description: Overview of the @lifi/wdk-protocol-swidge-lifi module for LI.FI swap and bridge routes.
docType: explanation
schemaType: TechArticle
---
Expand All @@ -16,6 +16,7 @@ Use this module when an app needs live LI.FI route discovery, exact-input or exa
- **EVM account support**: Works with `@tetherto/wdk-wallet-evm` and `@tetherto/wdk-wallet-evm-erc-4337`.
- **Discovery without signing**: Supports chain and token discovery without a bound wallet account.
- **Fee controls**: Applies optional `maxNetworkFeeBps` and `maxProtocolFeeBps` limits before execution.
- **Gasless-friendly**: Opt-in `denyBridges: NATIVE_VALUE_BRIDGE_DENY_LIST` and `allowNativeValue: false` filter native-value bridge routes and reject native-value quotes, so ERC-4337 sponsored execution can cover gas without the LI.FI route requiring separate native token value.
- **Reliability controls**: Provides request timeouts, retry handling, rate-limit classification, and typed LI.FI errors.
- **Transaction validation**: Validates quote transaction data before forwarding it to the wallet account.
- **Optional contract allowlist**: `trustedContracts` can require quote targets and approval addresses to match known LI.FI contracts.
Expand Down Expand Up @@ -47,10 +48,12 @@ Numeric LI.FI chain IDs are also accepted where the module accepts chain input.
| `WalletAccountEvm` | Quotes and executes routes. |
| `WalletAccountEvmErc4337` | Quotes and executes routes with smart-account gas handling. |
| `WalletAccountReadOnlyEvm` | Quotes, status lookups, and discovery only. |
| No account | Discovery and account-independent quote setup only. |
| No account | Chain and token discovery only. |

Use a read-only EVM account when you need quotes without signing. LI.FI quotes require a source address, so no-account mode is limited to chain and token discovery.

<Callout type="warn">
`swidge()` can approve and submit one or more EVM transactions. Show the quote, fee breakdown, destination token, destination chain, recipient, and refund address before calling it.
`swidge()` can approve and submit one or more EVM transactions. Show the quote, fee breakdown, destination token, destination chain, and recipient before calling it.
</Callout>

## Next Steps
Expand Down
24 changes: 18 additions & 6 deletions content/docs/sdk/swidge-modules/swidge-lifi/usage.mdx
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: LI.FI Swidge Usage
description: Install and use @kenny_io/wdk-protocol-swidge-lifi for LI.FI swap and bridge routes.
description: Install and use @lifi/wdk-protocol-swidge-lifi for LI.FI swap and bridge routes.
docType: how-to
schemaType: TechArticle
icon: BookOpen
Expand All @@ -9,7 +9,7 @@ icon: BookOpen
## Install

```bash
npm install @kenny_io/wdk-protocol-swidge-lifi
npm install @lifi/wdk-protocol-swidge-lifi
```

Install the wallet module for the account type you plan to use:
Expand All @@ -23,7 +23,7 @@ npm install @tetherto/wdk-wallet-evm-erc-4337

```javascript
import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm'
import { LifiSwidgeProtocol } from '@kenny_io/wdk-protocol-swidge-lifi'
import { LifiSwidgeProtocol } from '@lifi/wdk-protocol-swidge-lifi'

const account = new WalletAccountEvm(seedPhrase, "0'/0/0", {
provider: 'https://mainnet.infura.io/v3/YOUR_KEY'
Expand Down Expand Up @@ -62,7 +62,6 @@ const quote = await swidge.quoteSwidge({
toToken: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
toChain: 'arbitrum',
recipient: '0xRecipient...',
refundAddress: '0xRefund...',
fromTokenAmount: 10_000_000n,
slippage: 0.01
})
Expand Down Expand Up @@ -92,7 +91,6 @@ const result = await swidge.swidge({
toToken: '0xdAC17F958D2ee523a2206206994597C13D831ec7',
toChain: 'arbitrum',
recipient: '0xRecipient...',
refundAddress: '0xRefund...',
fromTokenAmount: 10_000_000n
}, {
maxNetworkFeeBps: 100,
Expand All @@ -103,6 +101,20 @@ console.log('Swidge ID:', result.id)
console.log('Transaction hash:', result.hash)
```

### Guard a quote-first flow with `minAmountOut`

`swidge()` fetches a fresh quote at execution time, which can differ from the quote the user reviewed. Pass `minAmountOut` — the `toTokenAmountMin` from the displayed quote — to reject execution if the fresh quote's minimum output has dropped below what the user accepted. The guard runs before any approval or transaction is sent, and the value is never forwarded to LI.FI.

```javascript
const quote = await swidge.quoteSwidge(options)
// ...user reviews and confirms the quote...

const result = await swidge.swidge({
...options,
minAmountOut: quote.toTokenAmountMin
})
```

## Track Status

Use `getSwidgeStatus()` with the returned operation ID. Chain hints can speed up indexing.
Expand All @@ -126,7 +138,7 @@ import {
LifiRateLimitError,
LifiSlippageError,
LifiTimeoutError
} from '@kenny_io/wdk-protocol-swidge-lifi'
} from '@lifi/wdk-protocol-swidge-lifi'

try {
await swidge.swidge(options)
Expand Down