API Reference

Class: VeloraProtocolEvm

Main class for velora token swaps on EVM.

Constructor

new VeloraProtocolEvm(account, config?)

Parameters:

account: IWalletAccount | IWalletAccountReadOnly from @tetherto/wdk-wallet
config (optional):
- swapMaxFee (bigint): exclusive cap in the fee units returned by the account's quote

The declarations accept the shared wallet interfaces. The implementation also reads account._config.provider and requires an EVM-compatible JSON-RPC URL or EIP-1193 provider. An interface match alone does not establish compatibility. Quoting needs getAddress() and quoteSendTransaction(); execution additionally requires a callable sendTransaction().

Example:

const swap = new VeloraProtocolEvm(account, { swapMaxFee: 200000000000000n })

Methods

Method	Description	Returns
`swap(options, config?)`	Perform a token swap	`Promise<{hash: string, fee: bigint, tokenInAmount: bigint, tokenOutAmount: bigint}>`
`quoteSwap(options, config?)`	Get estimated fee and amounts	`Promise<{fee: bigint, tokenInAmount: bigint, tokenOutAmount: bigint}>`

`swap(options, config?)`

Execute a swap via velora.

Options:

tokenIn (string): Address of the ERC‑20 token to sell
tokenOut (string): Address of the ERC‑20 token to buy
tokenInAmount (bigint, optional): Exact input amount (base units)
tokenOutAmount (bigint, optional): Exact output amount (base units)
to (string, optional): Recipient address (defaults to account address)

Config (optional; wallet gas-payment fields depend on the account):

paymasterToken ({ address: string }, optional): Paymaster token override for this swap
isSponsored (true, optional): Use sponsorship mode for this swap
sponsorshipPolicyId (string, optional): Sponsorship policy override
useNativeCoins (true, optional): Pay fees in the chain's native token
swapMaxFee (bigint, optional): Per-swap exclusive fee cap, in the account quote's units

Since beta.8, swap() passes one transaction object and the same config to the account's quoteSendTransaction() and sendTransaction(). It does not select the path by concrete account class. Standard WDK EVM accounts ignore wallet paymaster/sponsorship fields, but the protocol applies a per-call swapMaxFee for these accounts too.

The per-call cap overrides the constructor cap. A quote equal to or above that cap rejects the swap before sending. Match the cap to the quote's denomination: native wei for standard EVM/native-coin fees, paymaster-token base units for token-paid fees, or zero for sponsored quotes. A zero cap rejects even a zero-fee quote. quoteSwap() itself does not enforce the cap.

Returns:

Standard account: { hash, fee, tokenInAmount, tokenOutAmount }
ERC‑4337 account: { hash, fee, tokenInAmount, tokenOutAmount }

Notes:

Approve the input token with the account's approve() method before swapping if the spender does not already have enough allowance.
Requires a provider; requires a non read‑only account to send transactions.

Example:

const tx = await swap.swap({
  tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt on Ethereum
  tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH on Ethereum
  tokenInAmount: 1000000n
})

`quoteSwap(options, config?)`

Get estimated fee and token in/out amounts.

Options are the same as swap.

Returns: { fee, tokenInAmount, tokenOutAmount }

Config (ERC‑4337 only):

paymasterToken ({ address: string }, optional): Paymaster token override for fee estimation
isSponsored (true, optional): Use sponsorship mode for fee estimation
sponsorshipPolicyId (string, optional): Sponsorship policy override
useNativeCoins (true, optional): Estimate fees in the chain's native token

The protocol forwards one transaction object and config to any compatible account's quoteSendTransaction(). The account determines which wallet options apply; standard WDK EVM accounts ignore the ERC-4337 fields. The returned fee keeps the account's denomination. Quoting does not enforce swapMaxFee or reserve a route for later execution.

Works with read‑only accounts.

Example:

const quote = await swap.quoteSwap({
  tokenIn: '0xdAC17F958D2ee523a2206206994597C13D831ec7', // USDt on Ethereum
  tokenOut: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2', // WETH on Ethereum
  tokenOutAmount: 500000000000000000n // 0.5 WETH
})