Configuration

Swap Service Configuration

The VeloraProtocolEvm accepts a configuration object that defines fee controls and behavior:

import VeloraProtocolEvm from '@tetherto/wdk-protocol-swap-velora-evm'
import { WalletAccountEvm } from '@tetherto/wdk-wallet-evm'

// Create wallet account first
const account = new WalletAccountEvm(seedPhrase, "0'/0/0", {
  provider: 'https://ethereum-rpc.publicnode.com'
})

// Create swap service with configuration
const swapProtocol = new VeloraProtocolEvm(account, {
  swapMaxFee: 200000000000000n // Optional: Exclusive fee cap in wei for this EVM account
})

The swap service reads account._config.provider for network access. The account must expose an EVM-compatible JSON-RPC URL or EIP-1193 provider, plus getAddress() and quoteSendTransaction(). Execution also requires a callable sendTransaction(). A shared interface type alone does not make a non-EVM account compatible.

For accounts governed by WDK transaction policies, use wdk.registerProtocol() and the account's protocol getter. Do not pass the governed account proxy directly to this constructor: that proxy hides _config.

import { WalletAccountEvm, WalletAccountReadOnlyEvm } from '@tetherto/wdk-wallet-evm'

// Full access account
const account = new WalletAccountEvm(
  seedPhrase,
  "0'/0/0",
  {
    provider: 'https://ethereum-rpc.publicnode.com'
  }
)

// Read-only account (quotes only)
const readOnly = new WalletAccountReadOnlyEvm(
  await account.getAddress(),
  {
    provider: 'https://ethereum-rpc.publicnode.com'
  }
)

// Create swap service
const swapProtocol = new VeloraProtocolEvm(account, {
  swapMaxFee: 200000000000000n
})

Configuration Options

Swap Max Fee

The swapMaxFee option rejects execution when the account's quoted fee is equal to or greater than the cap. Since beta.8, the second argument to swap() can override this cap for standard EVM accounts as well as smart accounts. quoteSwap() does not enforce it.

Type: bigint (optional)
Unit: The account quote's fee units: native wei for standard EVM or native-coin fees, paymaster-token base units for token-paid fees, or zero for sponsored quotes. Choose a cap for the selected gas-payment mode; a zero cap rejects a zero-fee sponsored quote.

Examples:

// Ethereum standard EVM account; input allowance must already be sufficient
try {
  const result = await swapProtocol.swap({
    tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt (6 decimals)
    tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH (18 decimals)
    tokenInAmount: 1000000n
  }, { swapMaxFee: 200000000000000n }) // Exclusive cap of 0.0002 ETH
} catch (error) {
  if (error.message === 'Exceeded maximum fee cost for swap operation.') {
    console.error('Swap stopped: Fee too high')
  } else {
    throw error
  }
}

ERC‑4337 (Account Abstraction) Configuration

When using ERC‑4337 smart accounts (@tetherto/wdk-wallet-evm-erc-4337), you can override fee behavior per swap and specify a paymaster token:

import { WalletAccountEvmErc4337 } from '@tetherto/wdk-wallet-evm-erc-4337'

const aa = new WalletAccountEvmErc4337(seedPhrase, "0'/0/0", {
  chainId: 1,
  provider: 'https://ethereum-rpc.publicnode.com',
  bundlerUrl: 'YOUR_BUNDLER_URL',
  paymasterUrl: 'YOUR_PAYMASTER_URL',
  paymasterAddress: process.env.PAYMASTER_ADDRESS,
  safeModulesVersion: '0.3.0',
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  }
})

const swapAA = new VeloraProtocolEvm(aa)

const result = await swapAA.swap({
  tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt on Ethereum
  tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH on Ethereum
  tokenInAmount: 1000000n
}, {
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  },
  swapMaxFee: 10000n // Exclusive cap of 0.01 USDt for this token-paid quote
})

Per-call ERC‑4337 Config

The protocol passes the second argument to the account's quote and send methods without a concrete-class check. Compatible ERC-4337 accounts use it to select paymaster-token, sponsorship, or native-coin behavior. Standard WDK EVM accounts ignore those wallet fields, but the protocol still applies swapMaxFee from the second argument to swap(). Quote and execution receive one transaction object, not an ERC-4337-specific array.

The paymaster service must support the chosen chain and token. Configure its own endpoint and contract address; PAYMASTER_ADDRESS is deployment-specific. Approve the swap's input token for the current Velora spender before executing. The module does not create that approval for you. To change a nonzero Ethereum USD₮ allowance to another nonzero amount, first approve zero and wait for confirmation, then approve the new amount and wait again.

Type: partial ERC‑4337 wallet config (optional)

Example:

const result = await swapAA.swap({
  tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt on Ethereum
  tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH on Ethereum
  tokenInAmount: 1000000n
}, {
  paymasterToken: {
    address: '0xdAC17F958D2ee523a2206206994597C13D831ec7'
  },
  swapMaxFee: 10000n // Exclusive cap of 0.01 USDt for this token-paid quote
})

Network Support

velora supports multiple EVM networks (e.g., Ethereum, Polygon, Arbitrum). Ensure your account is configured with a valid provider for the target network.

// Ethereum Mainnet
const eth = new WalletAccountEvm(seedPhrase, "0'/0/0", {
  provider: 'https://ethereum-rpc.publicnode.com'
})

// Polygon
const polygon = new WalletAccountEvm(seedPhrase, "0'/0/0", {
  provider: 'https://polygon-bor-rpc.publicnode.com'
})

Swap Options

When calling swap, provide the swap parameters:

const swapOptions = {
  tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt on Ethereum
  tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH on Ethereum
  tokenInAmount: 1000000n,       // exact input (base units)
  // OR
  // tokenOutAmount: 1000000000000000n, // Alternative: exact output of 0.001 WETH
  to: await account.getAddress() // Optional recipient; defaults to this account
}

const result = await swapProtocol.swap(swapOptions)