Symbiosis Swidge Overview

Use @symbiosis-finance/wdk-protocol-swidge-symbiosis@1.3.0 when your wallet needs a WDK SwidgeProtocol provider for routes served by Symbiosis. The module uses the public Symbiosis REST API for discovery, quotes, execution payloads, and cross-chain status.

The released source is tagged v1.3.0 and maintained by Symbiosis.

When to use it

Use this module when your application needs:

• same-chain swaps, cross-chain bridges, or combined swap-and-bridge routes;
• runtime chain and token discovery;
• exact-input quotes;
• EVM, Bitcoin, TON, Tron, or Solana source execution through a WDK wallet account with the route-required capabilities;
• cross-chain settlement status mapped to WDK status values.

TON, Tron, and Solana source routes execute when the bound wallet account supports the transaction format the route requires. The module probes the account at execution time; on wallet versions without the capability those routes stay quote-only and swidge() throws UnsupportedRouteError.

Responsibility model

Discovery is not a route guarantee

getSupportedChains() and getSupportedTokens(options?) read provider-maintained catalogs. getSupportedTokens() filters the token catalog by toChain when present, otherwise by fromChain. It does not prove that a specific token pair currently has liquidity.

Call quoteSwidge() for the requested pair before presenting a route. Treat the returned quote as indicative because execution obtains a fresh response.

Quote and execution model

quoteSwidge() calls the Symbiosis quote endpoint and does not write to the wallet.

swidge() calls the Symbiosis swap endpoint again. The execution amounts, fees, spender, transaction payload, or Bitcoin deposit address can differ from the earlier quote. The method checks configured fee caps on this fresh response and then proceeds to the route-specific wallet writes.

For a non-native EVM input token, swidge() can:

1. Read the current allowance.
2. Reset a non-zero insufficient allowance to zero and, when the account supports receipt lookup, wait for that approval receipt.
3. Approve the spender returned by Symbiosis for the input amount and, when supported, wait for that receipt.
4. Broadcast the route transaction.

The method returns after the source transaction is broadcast. Use getSwidgeStatus(result.id) to track destination settlement or a refund.

Source execution support

Destination support is provider-controlled. Use runtime discovery and a successful quote instead of maintaining a static route list.

Integrator limitations

• Only exact-input routes are supported. Passing toTokenAmount throws ExactOutNotSupportedError.
• TON source routes are executed only when the provider returns a single transfer message. The TON wallet account reads a fresh sequence number per send without waiting for inclusion, so a multi-message route could execute partially; such routes throw UnsupportedRouteError.
• fromTokenAmount must convert to a positive integer bigint; invalid, zero, and negative values throw ValidationError before an API request.
• The module does not validate slippage ranges or the formats of recipient, refund, and partner addresses. Validate those application inputs before calling the provider.
• Discovery responses are cached for ten minutes per protocol instance. The cache duration is not configurable.
• Monero and Zcash are excluded from discovery and chain resolution because their provider routes use third-party custodial integrations outside this module's scope.
• A status lookup returning HTTP 404 is mapped to pending. A newly submitted operation and a genuinely unknown ID are therefore indistinguishable through this method.
• API requests time out after timeoutMs (30 seconds by default). The module does not retry or back off automatically.
• The package documents /v2/swap as rate-limited to one request per second. Bitcoin execution also uses that endpoint to generate a deposit address.
• If allowance lookup fails, the module falls back to sending an approval without a reset. That direct approval can still fail for a token with an existing non-zero allowance, so ensure allowance reads work or manage the reset in the application.
• If the wallet does not expose transaction-receipt lookup, the module cannot wait for approval confirmation before submitting the route transaction.
• A fee whose description is exactly Partner fee maps to affiliate; every other fee maps to protocol. No fee maps to network, so maxNetworkFeeBps does not constrain a separately reported network cost and maxProtocolFeeBps does not constrain the affiliate fee.
• Quote-only construction without an account uses recipient as both the source sender and destination recipient.
• The package exposes ESM and Bare entrypoints but does not declare a Node.js engines range.

Next steps

---

Need Help?