BOB Gateway Swidge Usage

Use GatewaySwidge to discover assets and quote a route before binding a signing account. The examples below make read-only gateway requests; they do not create orders or sign transactions.

Installation

The upcoming @gobob/wdk-protocol-swidge-gateway@0.5.0 release is pending publication. A version-pinned installation command will be added after its package is available and checked. Wait for it before running these examples.

The package name is @gobob/wdk-protocol-swidge-gateway. It uses ESM imports and requires @tetherto/wdk-wallet >=1.0.0-beta.17 <2.0.0 as a peer. Add WDK Core and concrete wallet packages only when your application imports them.

Node.js 24 is supported. Provide global fetch, or inject an HTTP transport or gateway client. The Bare package entry initializes its compatibility layer; this alone does not establish that every wallet or route works in a native host. See transport configuration for the available overrides.

Discover chains and tokens

import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'

const gateway = new GatewaySwidge()

const chains = await gateway.getSupportedChains()
const tokens = await gateway.getSupportedTokens()

Use each returned token's chain, token, symbol and decimals to populate your selector. Match tokens by both chain and token identifier. Metadata comes from the package's token table; tokens with no entry are omitted.

getSupportedTokens({ fromChain: chainId }) filters the returned token entries to that chain. It does not validate a source/destination pair or filter all tokens reachable from that source. The implementation does not use the shared interface's fromToken or toChain filters.

A fresh quote establishes whether the provider accepts a particular pair and amount. Discovery can also include destination chains for which this package has no source-signing adapter.

Preview a Bitcoin route

The function below accepts your selected destination token and chain, the intended recipient, a Bitcoin refund address you control and an input amount in satoshis. Choose those values in your application before calling it. For a USD₮ destination, verify the chain-specific token identifier independently rather than selecting by symbol alone.

import { BTC, GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'

export async function previewBitcoinRoute({
  destinationChain,
  destinationToken,
  recipientAddress,
  refundAddress,
  amountSats
}) {
  const gateway = new GatewaySwidge(undefined, {
    fromChain: 'bitcoin',
    refundAddress
  })

  const quote = await gateway.quoteSwidge({
    fromToken: BTC,
    toToken: destinationToken,
    toChain: destinationChain,
    fromTokenAmount: amountSats,
    recipient: recipientAddress,
    slippage: 0.01
  })

  return { gateway, quote }
}

Pass amountSats as a bigint. JavaScript runtime validation also accepts non-negative decimal integer strings, but the exported TypeScript amount fields admit only number | bigint. Native BTC uses satoshis; other amounts use their token's base units. For example, the source amount 100_000n represents 0.001 BTC, without asserting that this amount currently meets the gateway's route limits.

BTC is the package's alias for native Bitcoin. Use it only when the corresponding chain is bitcoin; other tokens use their chain-specific identifier.

Cross-chain requests require recipient. The recipient must be an address you intend to pay on the destination chain; the refund address is on the source chain. For a same-chain request, an account-bound instance can default the recipient to the account's address.

Bind the sending account

For execution, use an account your application already initialized with its chain's wallet module and RPC provider. Match sourceChain to that account and provider before constructing the protocol:

import { GatewaySwidge } from '@gobob/wdk-protocol-swidge-gateway'

export function bindSourceAccount(sourceAccount, sourceChain) {
  return new GatewaySwidge(sourceAccount, { fromChain: sourceChain })
}

Bitcoin sources need an account that can sign Bitcoin transactions; EVM and TRON sources need their corresponding transaction sender. An address-only account cannot execute. See EVM account setup, Bitcoin account setup, or TRON account setup.

Read the quote

See the API Reference for the complete result shape and error contracts.

To execute, create an instance bound to the source account and provide a recipient and refund address appropriate to the chosen chains. swidge() requests its own quote; the earlier preview does not lock the displayed output. The execution guide covers approval and fee boundaries, and Bitcoin Routes covers local signing and gateway broadcast.

Next Steps

Need Help?