BOB Gateway Swidge API Reference

Use GatewaySwidge to discover routes, obtain exact-input quotes, submit source transactions and track gateway orders. See installation availability before using this API.

Package exports

Import runtime values from the package root:

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

GatewaySwidge is also a named export. BTC is the string 'BTC', normalized to the gateway's native-Bitcoin identifier; it is rejected when used for a chain other than Bitcoin.

The root also exports WDK's AccountRequiredError, BridgeError, MaximumFeeExceededError, SwapError, SwidgeError, SwidgeErrorReason and ValueError. Internal adapter, mapper and transport source files are not package subpaths.

Import declarations separately:

import type {
  GatewaySwidgeConfig,
  GatewayClientConfig,
  GatewaySwidgeQuote,
  SwidgeOptions,
  SwidgeSimulation,
  EvmRequiredApproval,
  HttpTransport,
  TronApprovalCall,
  TronWebLike
} from '@gobob/wdk-protocol-swidge-gateway'

Additional exported types are Affiliate, BtcSimulateResult, EvmSimulateResult, TronSimulateResult, IWalletAccount, IWalletAccountReadOnly, and the WDK SwidgeCommonOptions, SwidgeExactInOptions, SwidgeExactOutOptions, SwidgeFee, SwidgeFeeType, SwidgeProtocolConfig, SwidgeQuote, SwidgeResult, SwidgeStatus, SwidgeStatusOptions, SwidgeStatusResult, SwidgeSupportedChain, SwidgeSupportedToken, SwidgeSupportedTokensOptions and SwidgeTransaction. The exported exact-output type does not mean this provider accepts exact-output requests.

The package has an ESM entry and a conditional Bare entry that initializes its runtime compatibility layer. The default HTTP path requires fetch and abort support. See Configuration for custom transport requirements.

GatewaySwidge

Constructor

new GatewaySwidge(
  account?: IWalletAccountReadOnly | IWalletAccount,
  config?: GatewaySwidgeConfig
)

An account is optional for discovery, status and quotes with an explicit recipient. Construction performs no gateway request. Source chain and destination settings must resolve when an operation is called.

The signing/estimation capability guards run before gateway calls. Structural account types alone do not establish chain compatibility. Discovery can include chains for which the package has no source-transaction adapter.

See Configuration for all constructor fields, precedence and provider prerequisites.

Methods

Swidge options

quoteSwidge() and swidge() accept WDK SwidgeOptions. The relevant options are:

For TypeScript, the re-exported SwidgeOptions admits number | bigint for fromTokenAmount and minAmountOut. Decimal strings are accepted by JavaScript runtime validation, but not by those declarations. The provider-specific maxNativeFee declaration includes strings.

toTokenAmount is rejected: this module supports exact input only. Set the source chain in the constructor's fromChain; the source account and its provider must match it.

quoteSwidge

The returned quote contains:

Mapped fees are included in the quoted output. Do not sum amounts across different tokens. A successful preview does not enforce execution fee caps or bind the later swidge() call to the same quote.

swidge

The second argument accepts maxNetworkFeeBps, maxProtocolFeeBps, maxNativeFee and paymasterToken. The first two override their constructor limits; maxNativeFee is a source-native amount and paymasterToken is forwarded only on the ERC-4337 EVM send path.

Execution fetches a fresh quote, checks output and applicable fee limits, creates an order, validates its source transaction, then signs and submits it. On EVM and TRON, the pre-sign checks constrain the source chain, pinned AllowanceHolder, source token, amount and extra native value. They do not independently verify every nested routing instruction or destination payout.

The result contains id (gateway order ID), hash (source transaction hash), quote amounts and fees, and a source entry in transactions. The destination amount is still a quote, not a settlement receipt.

On Bitcoin, the gateway broadcasts the locally signed transaction. EVM and TRON execution send through the account. Errors can follow a submitted transaction; reconcile the order and chain before retrying.

simulateSwidge

The second argument accepts basis-point caps and maxNativeFee, as for execution. The return value always contains variant, orderId, quote and broadcast: false, plus one source result:

Simulation creates a real, unfunded gateway order. EVM estimation or allowance-read failures and TRON build/read failures can be returned as valid: false with a reason; earlier input, quote or order-validation failures still reject. A valid result does not guarantee later execution or settlement.

See Bitcoin Routes before using Bitcoin simulation.

getRequiredApproval

Requires fromToken, toToken and fromTokenAmount together with the route's other options. The second argument accepts only maxNativeFee; it does not enforce minAmountOut or the percentage fee caps.

Returns null for a Bitcoin-source route, native source token, or sufficient existing allowance. Otherwise it returns:

On a spender-cache miss, this method creates an unfunded gateway order, validates its source transaction and caches the spender for that route on the instance. It then reads allowance. It does not send an approval.

The returned amount is not the requested trade amount. Obtain approval for the allowance being granted and wait for each approval transaction before executing. When resetRequired is true, reset to 0n first. Follow Execute a Swidge for EVM and TRON approval flows.

getSwidgeStatus

Takes the order id returned by execution. Its optional WDK status options are accepted but unused.

Possible mapped values are pending, refund-pending, completed, refunded and failed. These are not a guaranteed sequence. The result includes every available source, destination and refund hash in transactions. An unrecognized provider status throws instead of being assumed pending.

See Track Settlement for polling and submission recovery.

getSupportedChains

Reads both source and destination chains from gateway routes, returning each chain's ID, name, type and native token. This does not prove a route exists for a particular amount or that this package can sign from every returned chain.

getSupportedTokens

Accepts optional WDK SwidgeSupportedTokensOptions; the implementation reads only fromChain. When supplied, it keeps token entries whose own chain exactly matches that value, including entries found on the destination side of a route. It does not select all destinations reachable from that source.

Each returned token has token, chain, address and shipped metadata including symbol and decimals. Tokens absent from that metadata table are omitted. Use live discovery rather than an exhaustive static asset list.

Inherited swap and bridge methods

swap(), quoteSwap(), bridge() and quoteBridge() delegate through the WDK base protocol. Swap aliases use same-chain options. Bridge aliases reuse the same token identifier for source and destination, so they cannot map different token contracts across chains.

Use swidge() with explicit source and destination token identifiers for those routes. A shared native sentinel between chains with different native assets can describe a swap rather than a transfer of the same asset, and a bridge result does not identify the delivered token.

buildTronApproval

buildTronApproval(approval, { feeLimit? }) returns a TronApprovalCall descriptor for approve(address,uint256). It does not submit a transaction. The input has token, spender and amount; feeLimit defaults to 100000000 sun (100 TRX).

Send the descriptor with the TRON account's sendTransaction() and confirm the approval before the swidge. This helper constructs the requested allowance; it does not reduce an unbounded amount automatically.

GatewayClient

The low-level client accepts GatewayClientConfig and exposes gateway wire responses without WDK quote, status or transaction validation. Each method returns Promise<unknown>.

For registerTx(), the wire body is { onramp: { order_id, bitcoin_tx_hex } }. It contains a broadcastable transaction and must not be logged or exposed. Prefer GatewaySwidge for validated wallet flows.

The client's configuration is apiUrl, bearerToken, http, timeoutMs, allowInsecureApiUrl and maxRetries. Defaults and retry/transport boundaries are described in Configuration.

Errors

GatewaySwidgeError exposes code: string, optional status and cause: unknown. Do not display or log unfiltered causes, which can contain request or transaction details.

An exception is not proof that no transaction was submitted. Keep order and transaction identifiers and use the settlement guide before repeating a send.

Next Steps

Need Help?