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

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)
• minAmountOut (bigint, optional): Minimum output in the destination token's base units
• to (string, optional): Recipient address (defaults to account address)

Pass exactly one of tokenInAmount (SELL) or tokenOutAmount (BUY). Since beta.9, both quote and execution reject a rate whose token pair or exact amount differs from the request. Both reject a quoted output below minAmountOut. For SELL, the transaction builder receives that floor as its destination amount; without a floor it receives the quoted output. BUY keeps the requested exact output, which must also satisfy any supplied floor.

Each call fetches a fresh rate. Passing an earlier quote's accepted minimum to swap() constrains the new request; it does not retain the earlier route or quote.

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 }

The token amounts come from the rate used to build the transaction. They are quoted amounts, not measured settlement amounts. Confirm the transaction and inspect its result before reporting tokens received.

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 (optional; wallet gas-payment fields depend on the account):

• 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
})

Errors

Common errors include:

• Insufficient liquidity / no route for pair
• Quoted fee is equal to or greater than swapMaxFee
• Read‑only account cannot send swaps
• Provider/RPC errors (invalid endpoint, network mismatch)
• Velora quote does not match the requested swap.: The rate has a different pair or exact input/output amount; transaction building and submission do not proceed
• Velora quote is below the minimum output amount.: The rate fails the caller's minAmountOut; obtain a new acceptable quote before retrying

Types

• swapMaxFee: bigint: Exclusive cap in the account quote's fee units
• minAmountOut: bigint: Inclusive output floor in destination-token base units, available through shared SwapOptions
• tokenInAmount/tokenOutAmount: bigint — ERC‑20 base units
• paymasterToken: { address: string } — ERC‑4337 paymaster token override

Need Help?