Swidge Protocol Interface

The swidge interface is WDK's preferred route interface for protocol providers that can quote and execute asset movement. A swidge route moves from one token and chain to another token and chain. The provider may fulfill that route as a swap-only route, a bridge-only route, a combined swap and bridge route, an intent, a solver route, or an aggregator route.

When to use swidge

Use a swidge provider when a route matches any of these shapes:

• Swap one token into another token on the same chain.
• Bridge the same token from one chain to another chain.
• Swap and bridge in one route.
• Route between different tokens, different chains, or both.

Use the existing swap modules and bridge modules docs when maintaining released modules that have not shipped a swidge implementation yet. For new provider modules, prefer the swidge interface.

Interface methods

Concrete swidge provider modules extend SwidgeProtocol from @tetherto/wdk-wallet/protocols. The base interface exposes discovery, quote, execution, and status methods:

interface ISwidgeProtocol {
  quoteSwidge(options: SwidgeOptions): Promise<SwidgeQuote>
  swidge(
    options: SwidgeOptions,
    config?: SwidgeProtocolConfig
  ): Promise<SwidgeResult>
  getSwidgeStatus(
    id: string,
    options?: SwidgeStatusOptions
  ): Promise<SwidgeStatusResult>
  getSupportedChains(): Promise<SwidgeSupportedChain[]>
  getSupportedTokens(
    options?: SwidgeSupportedTokensOptions
  ): Promise<SwidgeSupportedToken[]>
}

Discover supported chains and tokens

Use getSupportedChains() and getSupportedTokens() before building route pickers or validating a requested route. These methods are read-only discovery calls; they do not quote or execute a transaction.

const chains = await swidge.getSupportedChains()
const ethereumTokens = await swidge.getSupportedTokens({
  fromChain: 'ethereum'
})

const routeTokens = await swidge.getSupportedTokens({
  fromChain: 'ethereum',
  fromToken: '0xSourceToken...',
  toChain: 'arbitrum'
})

getSupportedChains() returns provider-specific chain identifiers plus display metadata. getSupportedTokens(options?) returns provider-specific token identifiers, chain identifiers, symbols, decimals, and optional token addresses. Use the returned token and chain values when calling quoteSwidge() unless the provider module documents a stricter identifier format.

Quote a route

Call quoteSwidge() before execution so the user can review source amount, expected destination amount, minimum output, fees, and quote expiry.

const quote = await swidge.quoteSwidge({
  fromToken: '0xSourceToken...',
  toToken: '0xDestinationToken...',
  toChain: 'arbitrum',
  recipient: '0xRecipient...',
  fromTokenAmount: 1000000n,
  slippage: 0.01
})

console.log('Expected output:', quote.toTokenAmount)
console.log('Minimum output:', quote.toTokenAmountMin)
console.log('Fees:', quote.fees)

SwidgeOptions supports exact-in and exact-out routes:

Execute a route

Call quoteSwidge() first, show the quote to the user, then call swidge() with the same route options after explicit confirmation. Apply fee caps with SwidgeProtocolConfig where supported by the provider.

const options = {
  fromToken: '0xSourceToken...',
  toToken: '0xDestinationToken...',
  toChain: 'arbitrum',
  recipient: '0xRecipient...',
  fromTokenAmount: 1000000n,
  slippage: 0.01
}

const quote = await swidge.quoteSwidge(options)
// Show quote details and ask for confirmation before continuing.

const result = await swidge.swidge(options, {
  maxNetworkFeeBps: 50,
  maxProtocolFeeBps: 25
})

console.log('Swidge ID:', result.id)
console.log('Primary transaction:', result.hash)
console.log('Transactions:', result.transactions)

SwidgeProtocolConfig supports fee limits expressed in basis points of the input amount:

Track status

Use getSwidgeStatus() when the provider returns an execution ID and the final destination result may settle asynchronously.

const status = await swidge.getSwidgeStatus(result.id, {
  fromChain: 'ethereum',
  toChain: 'arbitrum'
})

if (status.status === 'completed') {
  console.log('Swidge complete')
}

Supported statuses are:

Result fields

SwidgeQuote and SwidgeResult can include an itemized fees array. Prefer displaying the itemized fees when available. Public fee categories are network, protocol, affiliate, and other; providers can use the optional fee description for route-specific detail.

Supported assets and chains

Provider modules should still document route shapes, network caveats, token identifier formats, and provider-specific limits on their module pages. Use getSupportedChains() and getSupportedTokens(options?) for runtime discovery, then consult the provider module docs for behavior that cannot be represented in the shared discovery response.

Next steps