LayerSwap Swidge API Reference

Reference the LayerSwap source adapters, shared methods, result fields and errors.

Community modules are developed and maintained independently by third-party contributors.

Tether and the WDK Team do not endorse or assume responsibility for their code, security, or maintenance. Use your own judgment and proceed at your own risk.

Imports and construction

Each source package exports its adapter class as the default. The common methods below apply to all four adapters.

import LayerswapProtocolEvm, {
  LayerswapApiClient,
  ProviderError,
  SwidgeError
} from '@layerswap/wdk-protocol-swidge-layerswap-evm'

The other default classes are LayerswapProtocolSolana, LayerswapProtocolBitcoin and LayerswapProtocolTon from their corresponding source packages. Use new Protocol(account, config?) with the matching account. An omitted account supports discovery and explicit-fromChain quotes; sending requires a writable account with that adapter's capabilities.

Type-only imports are separate:

import type {
  LayerswapProtocolConfig,
  LayerswapSwidgeOptions,
  LayerswapSwidgeConfig
} from '@layerswap/wdk-protocol-swidge-layerswap-evm'

Main methods

Method	Result	Side effects and constraints
`quoteSwidge(options)`	`Promise<SwidgeQuote>`	Exact-input quote without creating a provider swap. It does not validate recipient, refund address or minimum output. Source gas estimation can be omitted on failure.
`swidge(options, config?)`	`Promise<SwidgeResult>`	Creates a provider swap, prepares and sends the source deposit. Returns before destination settlement.
`getSwidgeStatus(id, options?)`	`Promise<SwidgeStatusResult>`	Reads the provider swap. Use the returned swap `id`, not its source `hash`.
`getSupportedChains()`	`Promise<SwidgeSupportedChain[]>`	Reads the cached provider catalog. Chain `id` is a provider network name.
`getSupportedTokens(options?)`	`Promise<SwidgeSupportedToken[]>`	Filters by `toChain`, otherwise `fromChain`; `fromToken` is ignored.
`getTransactionStatus(hash, options?)`	`Promise<LayerswapTransactionStatus>`	Returns `{ status }`, where `status` is `'completed'`, `'failed'` or `'pending'`. TON first resolves its message hash through TON Center.
`getApiClient()`	`LayerswapApiClient`	Returns the raw client described below.

There is no implemented local simulation method in these adapters. Discovery is a catalog query, not a route-capability or liquidity check.

Swidge options

Field	Meaning
`fromToken`	Required source token identifier. Prefer discovery's `token` field, which is a provider symbol.
`toToken`	Destination identifier required by the exported types. JavaScript runtime falls back to the source token's symbol when it is absent.
`fromChain`	Optional provider source network name; otherwise detected from the account.
`toChain`	Optional provider destination network name; omission selects the source network.
`fromTokenAmount`	Required exact-input base-unit integer. Use `bigint` for large values.
`toTokenAmount`	Unsupported; supplying it rejects an exact-output request.
`minAmountOut`	Accepted minimum in destination-token base units. Compared with the execution quote's minimum output.
`slippage`	Non-negative finite fraction; `0.005` means 0.5%.
`recipient`	Destination address. Fallback to the source account's address requires matching source/destination VM types.
`refundAddress`	Source-network refund address; defaults to the source account address.
`refuel`	Optional request for a destination native-gas drop.
`referenceId`	Optional reference for the provider swap.
`feeRate`	Bitcoin adapter only: fee rate in sat/vB.

Execution resolves fromChain and toChain by provider network name, even though some declarations admit numeric values. getSwidgeStatus() chain hints separately accept provider network names or chain IDs; getTransactionStatus() uses a provider network name for sourceChain. Use discovered names for operation options.

Token contract lookup recognizes a lowercase-0x prefix with 42 characters; other identifiers are matched as symbols. A non-EVM mint or contract address from the token's address metadata is not a universal accepted option value.

Constructor fields and per-call fee configuration are listed in Configuration. Amount and fee declarations use number | bigint; runtime conversion of integer options also accepts values convertible by BigInt. Prefer the declared types rather than depending on wider runtime coercion.

Quotes and execution results

Field	Quote	Execution	Meaning
`fromTokenAmount`	Yes	Yes	Source-token base units. A preview uses the caller's requested amount.
`toTokenAmount`	Yes	Yes	Provider-reported destination output in destination-token base units.
`toTokenAmountMin`	Yes	Yes	Provider minimum, falling back to receive amount when absent in a quote.
`fees`	Yes	Yes	Itemized fees with their own token, chain and inclusion context.
`estimatedDuration`	Optional	No	Provider completion-time estimate converted to seconds.
`id`	No	Yes	Provider swap ID for settlement polling.
`hash`	No	Yes	Source deposit hash; for TON, an external-message body hash.
`transactions`	No	Yes	Initially the source hash, chain and `type: 'source'`.

Execution with no quote in the create-swap response uses fees: [], toTokenAmount: 0n and toTokenAmountMin: 0n. A positive minimum output prevents broadcast in that case. Those placeholders are missing data, not independent verification of cost or settlement.

Each fee has type, amount and token, with optional chain, included and description. Included service/destination fees are in source-token units; separate source gas is in native units. See fee-limit behavior before interpreting a cap.

Status methods

getSwidgeStatus(id, { fromChain?, toChain? }) returns { status, transactions }. Hints constrain the lookup; a mismatch can produce NoSuchElementError.

The mapper recognizes action-required, pending, completed, failed, expired, cancelled, refund-pending and refunded. Unknown provider swap states fall back to pending. Do not interpret that fallback as proof the provider is making progress.

The first output transaction takes precedence when completed. Otherwise the first refund transaction determines refunded or refund-pending, and a non-completed first output is pending. Transactions without a hash are omitted; mapped transaction types are source, destination, refund and other.

getTransactionStatus(hash, { sourceChain? }) queries the source transaction separately and returns { status: 'completed' | 'failed' | 'pending' }. Read result.status, rather than comparing the whole result with a status string. NoSuchElementError can mean that the provider has not indexed it yet or that the lookup identifiers are wrong. See TON hash handling.

Swap and bridge adapters

Prefer the Swidge methods for new integrations. The explicit bridge adapter keeps the source hash in hash and returns the provider swap ID as swapId. Its fee is source gas in native units; bridgeFee is included provider cost in source-token units. Do not sum them across different assets.

bridge() and quoteBridge() take legacy fields: targetChain, recipient, token, amount, optional destinationToken, sourceChain, refundAddress, referenceId, refuel and percentage-string slippage. For 0.5%, Swidge takes 0.005 while bridge takes '0.5'.

bridge() and quoteBridge() wrap only SwidgeError as BridgeError; other errors pass through unchanged.

Inherited swap() and quoteSwap() are same-chain adapters. They use the provider swap ID as their hash and aggregate fee amounts, which does not preserve the full Swidge denomination breakdown.

Raw client

getApiClient() returns the same LayerswapApiClient instance used by the protocol. Its values are LayerSwap wire-format responses rather than WDK result shapes.

Method	HTTP request	Purpose
`getNetworks()`	`GET /api/v2/networks`	Cached network/token catalog.
`getQuote(params)`	`GET /api/v2/quote`	Read a prospective quote.
`getSwap(swapId)`	`GET /api/v2/swaps/{id}`	Read provider swap state.
`getTransactionStatus(networkName, transactionId)`	`GET /api/v2/transaction_status`	Read source deposit assessment.
`createSwap(params)`	`POST /api/v2/swaps`	Create a real provider swap.
`speedUpDeposit(swapId, transactionId)`	`POST /api/v2/swaps/{id}/deposit_speedup`	Notify the provider of a broadcast deposit.

The core package also exports pure mapping and unit-conversion helpers for adapter authors; they are separate from the protected protocol hooks.

The last two methods mutate provider state. Direct client calls bypass the protocol's route, amount, deposit and fee checks; they are not a replacement execution tutorial.

Errors

Import runtime error classes from the same adapter package used by your protocol.

Error	Common trigger
`AccountRequiredError`	No writable account for execution.
`DisposalError`	The bound account is disposed.
`ValueError`	Unsupported exact-output request, invalid integer option, invalid route/network or missing required recipient.
`InvalidTokenError`	Token lookup fails, or Bitcoin source is not native BTC.
`ProviderRequiredError`	The operation requires an account provider that is unavailable.
`ProviderError`	API/RPC failure, malformed provider response or deposit instructions, or a wallet error normalized to provider failure. It can carry `code`, `status` and `reason`.
`SwidgeError`	Minimum output is not met or a wallet error indicates insufficient funds.
`MaximumFeeExceededError`	A provider fee guard or the source wallet's fee policy rejects the operation.
`NoSuchElementError`	Swap/transaction is not found, not indexed yet, or does not match lookup hints.

A ValueError raised while selecting or preparing the provider's deposit instructions is normalized to ProviderError; it is not exposed as caller-input validation. A thrown error after source submission does not prove the deposit was absent; reconcile it before retrying.