Butter Network Swidge API Reference

Use ButterSwidgeProtocol to discover routes, request exact-input quotes, submit operations, and track their status.

Package exports

The package exports the same class as both its default export and named ButterSwidgeProtocol export. Import the class and any utilities from the package root:

import ButterSwidgeProtocol, {
  parseTokenAmount,
  formatTokenAmount,
  toButterSlippage,
  toEvmPublicClient
} from '@butternetwork/wdk-protocol-swidge-butter'

The package also exports ISwidgeProtocol, the public types, and error constructors listed below. Internal source files are not public package subpaths.

Node uses the standard ESM entry, which requires a fetch implementation and AbortController. Importing the package from Bare selects its conditional entry and initializes the bare-node-runtime compatibility layer. See Usage for runtime and installation prerequisites.

ButterSwidgeProtocol

The class extends WDK's SwidgeProtocol. Quoting and discovery can use undefined instead of an account. Execution requires an account capable of submitting the selected chain's transactions.

Constructor

The constructor binds the source chain, optional account, and integration settings:

new ButterSwidgeProtocol(
  account: ButterAccount | undefined,
  config: ButterSwidgeProtocolConfig
)

config requires sourceChainId and a Butter-issued entrance. Construction validates configuration and performs no API request or transaction. See Configuration for every field and execution prerequisite.

ButterAccount requires getAddress(), which returns a string or a promise of a string. Execution additionally requires sendTransaction(transaction). Allowance and receipt methods are optional in the type but may be required for ERC-20 execution or same-chain status. Built-in EVM execution requires an account that accepts Router calldata; matching the structural type alone does not establish chain compatibility.

Methods

quoteSwidge

Accepts WDK SwidgeOptions and returns a non-binding ButterSwidgeQuote. Only exact-input options work; supplying toTokenAmount throws ButterExactOutUnsupportedError before any API request. An account is not required, although a Solana-source quote needs an explicit recipient when no account address is available.

The quote includes an opaque routeHash and is cached only after its complete response has been validated. Quoting does not enforce configured fee caps. A successful quote does not guarantee that later execution will pass those caps, have sufficient lifetime, or complete settlement.

destinationGuarantees is enforced for the built-in same-chain EVM path, which validates the destination minimum against Router calldata. It is quoted-only for cross-chain or adapter execution. This field describes the validation path; it does not prove that a sending account is configured.

swidge

Accepts ButterSwidgeOptions and an optional WDK SwidgeProtocolConfig. The second argument overrides only maxNetworkFeeBps and maxProtocolFeeBps. The module does not forward it to the account's sender.

For a confirmed quote, pass its routeHash with the same route intent on the same protocol instance. A pin must match the cached route and have more than the configured execution margin remaining. It is consumed for one execution attempt, even if a later stage fails. Pins that are absent from the cache, stale, or mismatched throw ButterActionRequiredError; they are not silently replaced. Without a pin, execution can obtain a new route.

The built-in EVM path verifies the Router target, source amount, token, sender, and fee data. For same-chain operations, it also validates the recipient, minimum output, and leftover recipient. Cross-chain validation trusts Butter's nested destination routing. Adapter execution bypasses these EVM calldata checks and requires host validation.

For ERC-20 inputs, the module adjusts any differing allowance to the exact input amount, with a confirmed zero reset when necessary. See EVM approvals. The result is returned after source submission; use getSwidgeStatus() to track it.

getSwidgeStatus

Accepts a nonempty id string and optional ButterSwidgeStatusOptions. By default, id is the source transaction hash returned by swidge(). Set byOrderId: true only when the ID came separately from Butter; this module does not return order IDs.

Same-chain operations recorded by the instance use receipt status. For an unrecorded EVM operation, configure a public client with transaction and receipt lookup so the module can attribute the transaction to an allowlisted Butter Router. Explicit chain hints do not bypass attribution. Unverifiable same-chain IDs throw an error. Solana and Tron same-chain operations require the executing instance's record and the account's receipt method.

Cross-chain operations use Butter's status API. Reported source hashes and chain IDs are checked against the lookup and any retained operation context when available. The result contains status and any transaction records supplied by the status source.

A missing record or state throws ButterApiError. RPC failures propagate rather than being treated as absent transactions. Follow Track Settlement for bounded polling and partial-execution handling.

getSupportedChains

Takes no arguments. It combines Router-supported chains with metadata from Butter's token API and drops entries without usable IDs, types, or native-token symbols.

Each ButterSupportedChain contains id, name, type, nativeToken, and execution. Execution modes are native for a configured built-in EVM Router path, adapter for a configured adapter, or quote-only. These modes describe local configuration, not account readiness or liquidity. The instance remains bound to its constructor's source chain.

getSupportedTokens

Accepts optional WDK SwidgeSupportedTokensOptions. Chain selection uses fromChain, then toChain, then the instance's source chain. Butter's listing does not provide route-scoped fromToken filtering.

Entries contain token, chain, symbol, and decimals, with optional address and name. Use the token value as the provider identifier. The catalog is non-exhaustive; a token's absence does not establish that no route exists. Obtain a quote for the chosen pair and amount.

Malformed entries are dropped. Conflicting precision for the same canonical token causes ButterApiError. Validated entries can seed the instance's source-token decimal cache.

swap

Accepts WDK SwapOptions and delegates to swidge() on the instance's source chain. It maps tokenIn, tokenOut, to, tokenInAmount, tokenOutAmount, and minAmountOut to Swidge options. Exact-output tokenOutAmount is rejected by Butter.

Returns hash, fee, tokenInAmount, and tokenOutAmount. The inherited fee sums every fee amount across token denominations and categories. This delegation does not preserve Butter quote pins or an explicit slippage option. Use swidge() and its itemized fees when those details matter.

quoteSwap

Accepts the same WDK SwapOptions mapping as swap() and delegates to quoteSwidge(). Returns the legacy swap fields without hash. It performs no broadcast, but its aggregated fee and omitted route pin have the same limitations as swap().

bridge

Accepts WDK BridgeOptions: token, targetChain, recipient, and amount. It sends the same token identifier as both source and destination, and delegates to swidge(). Use the direct method when the two chains require different token identifiers.

Returns hash, fee, and bridgeFee. The inherited method sums network entries into fee and protocol entries into bridgeFee, omitting affiliate entries. A group containing different currencies has no meaningful single-token total. It does not forward a Butter route pin; direct Swidge methods retain that control.

quoteBridge

Accepts the same WDK BridgeOptions mapping as bridge() and delegates to quoteSwidge(). Returns fee and bridgeFee without broadcasting. The token-identifier and aggregated-fee limitations are the same as bridge().

Options

ButterSwidgeOptions

This type adds routeHash and maxNativeFee to WDK SwidgeOptions. The shared WDK union includes exact-output requests, but this provider rejects them at runtime.

The quote cache identity includes tokens, chain, amount, recipient, slippage, entrance, affiliate, and referrer. Caller minimum and refund constraints are checked separately where applicable. A route pin is not a durable identifier or protection against duplicate execution across separate attempts.

ButterSwidgeStatusOptions

Results

ButterSwidgeQuote

Source-token precision is resolved from configuration or validated discovery. Output precision comes from the route's destination metadata. Inspect fees by token and chain rather than adding unlike amounts; see Fee limits.

SwidgeResult

id and hash contain the source transaction hash. The result also includes transactions, fees, fromTokenAmount, toTokenAmount, and toTokenAmountMin. Output amounts remain route estimates; returning a result does not prove that the destination amount arrived.

Each transaction record contains hash, optional chain, and optional type. Roles are source, destination, approval, refund, and other. Butter execution reports every known broadcast transaction and uses the source transaction as the operation ID. Save the records before beginning status polling.

Utilities

parseTokenAmount

Convert a decimal amount to token base units with an explicit precision:

parseTokenAmount('1.25', 6) // 1250000n

Signature: parseTokenAmount(amount, decimals = 18, options = {}): bigint. amount accepts a decimal string, a nonnegative safe integer number, a bigint, undefined, or null. Decimal strings are scaled; a bigint is already in base units and passes through unchanged. Null or undefined returns 0n. Fractional numbers, negative values, and malformed strings are rejected.

options.rounding accepts 'reject', 'floor', or 'ceil'. The default rejects nonzero precision beyond the token's decimals. Decimal counts must be integers from 0 through 255. Use decimal strings when parsing user-entered fractional amounts.

formatTokenAmount

Format integer base units without converting through floating-point arithmetic:

formatTokenAmount(1250000n, 6) // '1.25'

Signature: formatTokenAmount(amount, decimals = 18): string. Accepts a nonnegative bigint, safe integer number, or decimal integer string. Fractional, signed, exponent, hexadecimal, and empty strings are rejected. Trailing fractional zeros are removed.

toButterSlippage

Convert a WDK decimal fraction to Butter's integer basis points:

toButterSlippage(0.01) // 100

Signature: toButterSlippage(slippage, options = {}): number. The first argument is a number or undefined. Options are crossChain, sourceChainId, toChainId, and strictChainMinimum. crossChain is boolean, chain IDs are strings or numbers, and strictChainMinimum is a basis-point number.

The converted value must be from 0 through 5000 basis points. Fractional basis points are rounded down; positive slippage below one basis point is rejected. When omitted, slippage defaults to 100 basis points, increased to the applicable minimum: 150 for cross-chain routes and 300 for Bitcoin or configured strict chains. An explicit value below the applicable minimum throws ButterActionRequiredError rather than being widened.

toEvmPublicClient

toEvmPublicClient(client: ViemPublicClientLike): EvmPublicClient adapts a viem read-only client. It wraps allowance reads, approval waits, and transaction or receipt lookup. See the execution guide for setup.

Only viem transaction-not-found and receipt-not-found errors become null during lookups. Other RPC failures propagate. This utility does not create a signer or send transactions.

Public types

These types are named exports from the package root. WDK result and option types referenced by their signatures are defined by @tetherto/wdk-wallet/protocols.

There is no public dispose(), automatic refund, allowance-revocation, or route-cache serialization method. Release the protocol instance when finished and manage the wallet's lifecycle through its own API.

Errors

Butter error constructors and the WDK categories below are exported from the package root. Catch narrower classes before their parent categories. Details can contain provider or account diagnostics; redact them before logging.

ButterPartialExecutionError exposes transactions, cause, and failedType. Fee-limit errors expose details.feeType, details.actualBps, and details.maximumBps, with the ratios represented as strings.

The package re-exports these unchanged WDK error constructors: WdkError, ValueError, UnsupportedOperationError, MaximumFeeExceededError, ProviderRequiredError, ProviderError, TransactionError, and AccountRequiredError. A first-send account error can propagate unchanged; after a known broadcast it is retained as the partial-execution cause.

An account can fail after submitting a transaction or return an unusable hash. Therefore, the absence of ButterPartialExecutionError is not proof that nothing was submitted. Check wallet and RPC state before retrying an uncertain submission.

Next Steps

Need Help?