Symbiosis Swidge Configuration

Constructor

new SymbiosisProtocol(account?, config?)

import SymbiosisProtocol from '@symbiosis-finance/wdk-protocol-swidge-symbiosis'

const symbiosis = new SymbiosisProtocol(account, {
  chain: 'Ethereum',
  timeoutMs: 30_000,
  partnerId: 'my-app',
  defaultSlippage: 0.02,
  refundAddress: 'bc1qRefund...',
  maxProtocolFeeBps: 100
})

Configuration fields

partnerId identifies the integrating application in an HTTP header. partnerAddress is a separate fee-share address included in quote and execution request bodies.

Source chain

Use a numeric ID or the exact name returned by getSupportedChains():

const byName = new SymbiosisProtocol(account, {
  chain: 'Ethereum'
})

const byId = new SymbiosisProtocol(account, {
  chain: 1
})

The configured chain must identify the bound account's source chain. The module does not derive or verify it from the wallet account.

Chain and token identifiers

Chain identifiers can be numeric Symbiosis IDs or case-insensitive names from getSupportedChains().

Token identifiers can be:

• a provider-listed contract or asset address;
• a token symbol on the selected chain;
• '', 'native', or the zero address for a native token.

For TON and Solana assets, token discovery returns the provider's native-format address when available.

Token symbols can be ambiguous. Prefer the exact address returned by getSupportedTokens() and confirm route availability with quoteSwidge().

Slippage and amounts

The per-call slippage option overrides defaultSlippage:

const quote = await symbiosis.quoteSwidge({
  fromToken,
  toToken,
  toChain,
  recipient,
  fromTokenAmount: 100_000_000n,
  slippage: 0.01
})

The module converts the decimal slippage value to basis points with Math.round(slippage * 10000). It does not validate the range of either slippage setting.

Pass fromTokenAmount as a positive base-unit integer. Missing values, values that cannot be converted with BigInt, zero, and negative amounts throw ValidationError before the API request.

Recipient, partner, and refund addresses

For a bound account, the source sender comes from account.getAddress(). recipient defaults to that address when omitted.

Without an account, recipient supplies both the source sender and destination recipient:

const quoteOnly = new SymbiosisProtocol(undefined, {
  chain: 'Ethereum'
})

const quote = await quoteOnly.quoteSwidge({
  fromToken: 'USDT',
  toToken: 'USDC',
  toChain: 'Arbitrum One',
  recipient: '0xRecipient...',
  fromTokenAmount: 100_000_000n
})

Set a refund address suitable for a deposit-address route:

const symbiosis = new SymbiosisProtocol(bitcoinAccount, {
  chain: 'Bitcoin',
  refundAddress: 'bc1qRefund...'
})

Override it for one request with options.refundAddress.

Approval behavior

For a non-native EVM input token, the module uses the spender returned by the fresh execution response.

By default it:

1. calls getAllowance(token, spender) when available;
2. skips approval when allowance covers the input amount;
3. resets a non-zero insufficient allowance to zero and waits for its receipt when the account supports receipt lookup;
4. approves the exact input amount and waits for its receipt when supported;
5. approves without a reset when allowance lookup fails.

When allowance lookup succeeds and the account returns transaction hashes, both approval hashes are included in result.transactions when a reset is required. This supports tokens such as USDT on Ethereum that reject a direct non-zero-to-non-zero allowance change. If allowance lookup fails while such a token already has a non-zero allowance, the fallback direct approval can still fail.

Disable the automatic step only when the host application manages allowance:

const symbiosis = new SymbiosisProtocol(account, {
  chain: 'Ethereum',
  skipApproval: true
})

skipApproval does not verify allowance. Insufficient allowance can cause the subsequent transaction to fail.

Fee caps

Set protocol-level defaults on the instance:

const symbiosis = new SymbiosisProtocol(account, {
  chain: 'Ethereum',
  maxProtocolFeeBps: 100
})

Override shared fee caps for one execution:

await symbiosis.swidge(options, {
  maxProtocolFeeBps: 75
})

The module checks the fresh /v2/swap response before calling a wallet write method.

When both the input token and fee token have positive USD price data, the module compares USD values. Otherwise it compares decimal-normalized token amounts. That fallback is approximate when the fee token and input token have different unit values.

No returned fee maps to network, so maxNetworkFeeBps remains at zero in this provider's current fee calculation. The module does not estimate the wallet transaction's chain fee.

Discovery caching

The provider caches chain and token discovery promises for ten minutes per instance. A failed request is removed from the cache and can be retried by a later call.

The cache duration has no public configuration field. Construct a new provider instance when the application must bypass cached discovery.

Monero and Zcash are filtered from chain discovery, token discovery, and chain resolution because their routes use third-party custodial integrations outside this module's scope.

API and runtime behavior

• The default entrypoint is ESM.
• The bare export initializes bare-node-runtime globals before loading the provider.
• The package declares no Node.js engines range.
• Requests use the runtime's global fetch.
• Requests use an internal AbortController and time out after timeoutMs; network failures and timeouts throw ApiError with status: 0.
• The provider does not retry or back off automatically.
• apiUrl is normalized only by removing trailing slashes.

Use a trusted https:// endpoint for apiUrl. Choose a timeout appropriate for the runtime and retry cautiously, especially around execution and status polling.