Symbiosis Swidge API Reference

Package exports

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.3.0.

SymbiosisProtocol

SymbiosisProtocol extends SwidgeProtocol.

Constructor

new SymbiosisProtocol(
  account?: IWalletAccount | IWalletAccountReadOnly,
  config?: SymbiosisProtocolConfig
)

chain is optional in the constructor type, but quoteSwidge() and swidge() throw ConfigurationError when it is absent.

Configuration type

type SymbiosisProtocolConfig = {
  chain?: string | number
  apiUrl?: string
  timeoutMs?: number
  partnerId?: string
  defaultSlippage?: number
  partnerAddress?: string
  refundAddress?: string
  skipApproval?: boolean
  maxNetworkFeeBps?: number | bigint
  maxProtocolFeeBps?: number | bigint
}

See Configuration for defaults, validation boundaries, and execution effects.

Methods

quoteSwidge(options)

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, is not an integer, or is not positive; 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, times out, or fails before a response is received. Network failures and timeouts carry status: 0.

The method can also propagate an error from account.getAddress().

swidge(options, config?)

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.

For ton, tron, and solana source routes, the method first probes the bound account for the transaction format the route requires (raw BoC message bodies, smart contract calls plus TRC-20 approvals, and serialized transactions respectively) and throws UnsupportedRouteError when the capability is missing or a ton route needs more than one message.

The optional second argument overrides maxNetworkFeeBps and maxProtocolFeeBps for this execution.

getSwidgeStatus(id, options?)

getSwidgeStatus(
  id: string,
  options?: SwidgeStatusOptions
): Promise<SwidgeStatusResult>

Pass the ID returned by swidge():

<sourceChainId>:<sourceTransactionHash>

For a bare transaction hash, pass options.fromChain or configure the instance source chain. The provider does not use other status hints.

The resolved source-chain ID and transaction hash are URL-encoded before the provider builds the status endpoint path.

HTTP 404 is returned as pending, not as ApiError.

getSupportedChains()

getSupportedChains(): Promise<SwidgeSupportedChain[]>

Calls the Symbiosis chain and token endpoints and maps each in-scope chain to:

Monero and Zcash are filtered out because their provider routes use third-party custodial integrations outside this module's scope.

getSupportedTokens(options?)

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.

The response is a token catalog, not proof of pair liquidity. Request a quote for route availability.

Relevant SwidgeOptions

The module does not validate slippage ranges or address formats. It converts fromTokenAmount with BigInt and throws ValidationError unless the result is greater than zero.

Quote and result fields

SwidgeQuote

The provider does not map a quote expiry into SwidgeQuote.

SwidgeResult

Status mapping

When status is refunded, a returned settlement transaction is labeled refund; otherwise it is labeled destination.

Fee mapping and caps

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.

ApiError.status is 0 when no HTTP response was received. 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.