Butter Network Swidge Usage

Check prerequisites, install the source snapshot, configure the client, discover provider data, and preview a quote. For support, see Need Help?. This flow does not submit transactions.

Prerequisites

• Node.js 22, npm, and Git.
• A Node application configured for ES modules, for example with "type": "module" in its package.json.
• A Butter-issued entrance identifier accepted by the Router API. Obtain integration access through Butter Network; do not assume an example identifier is provisioned for your application.
• Network access to the configured Butter APIs.

These pages target source version 0.2.0 at revision c1f373d. The published npm 0.1.0 package has a different API. Use the source installation below until a matching release is available.

Install the source snapshot

From your application's directory:

1. Check out the exact source revision in a separate vendor directory.
2. Install its locked build dependencies and pack the compiled module.
3. Install the archive and the compatible WDK wallet peer in your application.

Build and install the pinned source with these commands:

git clone https://github.com/butternetwork/wdk-protocol-swidge-butter.git vendor/butter-module
git -C vendor/butter-module checkout --detach c1f373d9876668502e0b23b351cb1e4db6328b7c
npm --prefix vendor/butter-module ci
npm pack ./vendor/butter-module --pack-destination "$PWD"
npm install ./butternetwork-wdk-protocol-swidge-butter-0.2.0.tgz @tetherto/wdk-wallet@1.0.0-beta.17

The pack step runs the source build. Retain the archive and its revision in your dependency records. Installing the older npm release does not reproduce this snapshot. Transaction execution also requires a suitable wallet module; the execution guide installs the EVM dependencies.

Configure the client

Set BUTTER_ENTRANCE in the server process environment. Create an accountless ButterSwidgeProtocol for Ethereum:

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

const entrance = process.env.BUTTER_ENTRANCE?.trim()
if (!entrance) throw new Error('Set your Butter-issued BUTTER_ENTRANCE')

const protocol = new ButterSwidgeProtocol(undefined, {
  sourceChainId: '1',
  entrance,
})

Authentication is optional at the module level, but Butter may require credentials for your integration. When needed, supply both apiKeyId and apiSecret and set authMode: 'required' in a server process. Never place the secret in browser or mobile code. See API access.

Discover provider data

Retrieve runtime chain data with getSupportedChains():

const chains = await protocol.getSupportedChains()
console.log('Advertised chains:', chains.length)

Each entry includes an execution classification. native identifies built-in Router support; it does not prove that an account, matching RPC, or liquid route is available. Filter provider data through your application's supported-chain and asset policies before displaying it.

Retrieve Ethereum's token catalog with getSupportedTokens():

const tokens = await protocol.getSupportedTokens({ fromChain: '1' })
console.log('Catalog entries for Ethereum:', tokens.length)

The catalog is non-exhaustive. A token can be absent yet routable, and catalog membership does not guarantee a quote. Use chain-specific token identifiers and verify decimals before constructing amounts.

Preview a quote

This example requests 0.001 ETH to Ethereum USD₮. The USD₮ contract and six-decimal precision come from Tether's supported protocols. Butter must still accept the integration, pair, and amount; this example does not guarantee route availability.

Create the intent with parseTokenAmount(). native is the module's native-token identifier; the input uses Ethereum's 18 decimals:

const ETHEREUM_USDt = '0xdAC17F958D2ee523a2206206994597C13D831ec7'
const USDt_DECIMALS = 6

const intent = Object.freeze({
  fromToken: 'native',
  toToken: ETHEREUM_USDt,
  fromTokenAmount: parseTokenAmount('0.001', 18),
  toChain: '1',
  slippage: 0.01,
})

Request the estimate with quoteSwidge() and format the output with formatTokenAmount():

const quote = await protocol.quoteSwidge(intent)
console.log('Estimated USDt output:', formatTokenAmount(quote.toTokenAmount, USDt_DECIMALS))
console.log('Minimum USDt output:', formatTokenAmount(quote.toTokenAmountMin, USDt_DECIMALS))
console.log('Expiry (Unix seconds):', quote.expiry)
console.log('Destination validation:', quote.destinationGuarantees)

Show each fees[] entry with its own token, chain, amount, and inclusion flag. Do not add amounts across different assets. Quotes do not enforce execution fee caps. enforced describes built-in same-chain EVM validation; cross-chain and adapter destination guarantees are quoted-only.

The accountless quote belongs to this instance. For execution, create a bound instance and obtain a new quote with the explicit recipient, then pass its routeHash on that same instance. Do not transfer a quote pin between instances.

Next Steps

Need Help?