End-to-end Transaction Example (Ethereum)

Quickstart: minimal working example

The following example demonstrates a complete transaction flow:

Fetches a quote from delora API for token swap
Checks and approves token allowance if needed
Executes the transaction using ethers.js v5

⚠️ Security Note: Never hardcode private keys or mnemonics in production code. Use environment variables or secure key management solutions.

import { ethers, BigNumber, Contract } from 'ethers';

const API_URL = 'https://api.delora.build/v1';

const ERC20_ABI = [
  'function allowance(address owner, address spender) view returns (uint256)',
  'function approve(address spender, uint256 amount) returns (bool)',
] as const;

const getQuote = async (params: {
  originChainId: number;
  destinationChainId: number;
  amount: string;
  originCurrency: string;
  destinationCurrency: string;
  senderAddress: string;
  receiverAddress?: string;
}) => {
  const query = new URLSearchParams();
  
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined) {
      query.append(key, String(value));
    }
  }
  
  const url = `${API_URL}/quotes?${query.toString()}`;
  const response = await fetch(url);
  
  if (!response.ok) {
    throw new Error(`Failed to get quote: ${response.status} ${response.statusText}`);
  }
  
  return response.json();
};

export const executeSwap = async (provider: ethers.providers.Web3Provider) => {
  await provider.send('eth_requestAccounts', []);
  const wallet = provider.getSigner();
  const walletAddress = await wallet.getAddress();

  const originChainId = 137;
  const destinationChainId = 137;
  const originCurrency: string = '0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359';
  const destinationCurrency = '0x2791Bca1f2de4661ED88A30C99A7a9449Aa84174';
  const amount = ethers.utils.parseUnits('100', 6).toString();

  const quote = await getQuote({
    originChainId,
    destinationChainId,
    amount,
    originCurrency,
    destinationCurrency,
    senderAddress: walletAddress,
    receiverAddress: walletAddress,
  });

  if (originCurrency !== ethers.constants.AddressZero) {
    const token = new Contract(originCurrency, ERC20_ABI, wallet);
    const allowance = await token.allowance(walletAddress, quote.calldata.to);
    
    if (allowance.lt(BigNumber.from(quote.inputAmount))) {
      await (await token.approve(quote.calldata.to, ethers.constants.MaxUint256)).wait();
    }
  }

  const tx = await wallet.sendTransaction({
    to: quote.calldata.to,
    data: quote.calldata.data,
    value: quote.calldata.value,
    ...(quote.gas?.gasLimit && { gasLimit: BigNumber.from(quote.gas.gasLimit) }),
    ...(quote.gas?.maxFeePerGas && { maxFeePerGas: BigNumber.from(quote.gas.maxFeePerGas) }),
    ...(quote.gas?.maxPriorityFeePerGas && { maxPriorityFeePerGas: BigNumber.from(quote.gas.maxPriorityFeePerGas) }),
    ...(quote.gas?.gasPrice && { gasPrice: BigNumber.from(quote.gas.gasPrice) }),
  });

  await tx.wait();
  
  return tx.hash;
};

React Integration Example

For React applications, you can integrate the swap function as follows:

import { ethers } from 'ethers';
import { executeSwap } from './example';

const SwapButton = () => {
  const handleSwap = async () => {
    if (!window.ethereum) {
      alert('Please install MetaMask or another Web3 wallet');
      return;
    }
    
    const provider = new ethers.providers.Web3Provider(window.ethereum);
    
    try {
      const txHash = await executeSwap(provider);
      console.log('Transaction hash:', txHash);
    } catch (error) {
      console.error('Swap failed:', error);
    }
  };

  return (
    <button onClick={handleSwap}>
      Execute Swap
    </button>
  );
};

Breaking it down

1. Building the quote request

The getQuote function constructs a query string from parameters and fetches the quote from the API: senderAddress is required, while receiverAddress is optional for same-type routes like this one and defaults to senderAddress.

const getQuote = async (params: {
  originChainId: number;
  destinationChainId: number;
  amount: string;
  originCurrency: string;
  destinationCurrency: string;
  senderAddress: string;
  receiverAddress?: string;
}) => {
  const query = new URLSearchParams();
  
  for (const [key, value] of Object.entries(params)) {
    if (value !== undefined) {
      query.append(key, String(value));
    }
  }
  
  const url = `${API_URL}/quotes?${query.toString()}`;
  const response = await fetch(url);
  
  if (!response.ok) {
    throw new Error(`Failed to get quote: ${response.status} ${response.statusText}`);
  }
  
  return response.json();
};

Key parameters:

originChainId / destinationChainId: Chain IDs (e.g., 1 for Ethereum, 137 for Polygon)
amount: Token amount in smallest unit (wei, satoshi, etc.)
originCurrency / destinationCurrency: Token contract addresses (0x0...0 for native tokens)
senderAddress: Required wallet address
receiverAddress: Optional for same-type routes; defaults to senderAddress. For routes across different chain types, provide it explicitly.

2. Wallet provider setup

The function accepts a Web3Provider from ethers.js, which can be obtained from various sources: Browser extension (MetaMask, etc.):

const provider = new ethers.providers.Web3Provider(window.ethereum);

RPC endpoint:

const provider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com', 137);

With wallet from mnemonic (development only):

const provider = new ethers.providers.JsonRpcProvider('https://polygon-rpc.com', 137);
const wallet = ethers.Wallet.fromMnemonic(process.env.MNEMONIC!).connect(provider);

⚠️ Never hardcode mnemonics or private keys in production code.

3. Token allowance and approval

For ERC-20 tokens (non-native), the contract must be approved to spend tokens on behalf of the user:

if (originCurrency !== ethers.constants.AddressZero) {
  const token = new Contract(originCurrency, ERC20_ABI, wallet);
  const allowance = await token.allowance(walletAddress, quote.calldata.to);
  
  if (allowance.lt(BigNumber.from(quote.inputAmount))) {
    await (await token.approve(quote.calldata.to, ethers.constants.MaxUint256)).wait();
  }
}

Notes:

Native tokens (ETH, BNB, etc.) don’t require approval
The spender address (quote.calldata.to) is the contract that will execute the swap
Using MaxUint256 avoids repeated approvals, but you can use the exact amount for better security

4. Transaction execution

The quote response includes transaction parameters (to, data, value) and optional gas estimates:

const tx = await wallet.sendTransaction({
  to: quote.calldata.to,      
  data: quote.calldata.data,  
  value: quote.calldata.value,
  ...(quote.gas?.gasLimit && { gasLimit: BigNumber.from(quote.gas.gasLimit) }),
  ...(quote.gas?.maxFeePerGas && { maxFeePerGas: BigNumber.from(quote.gas.maxFeePerGas) }),
  ...(quote.gas?.maxPriorityFeePerGas && { maxPriorityFeePerGas: BigNumber.from(quote.gas.maxPriorityFeePerGas) }),
  ...(quote.gas?.gasPrice && { gasPrice: BigNumber.from(quote.gas.gasPrice) }),
});

await tx.wait();

return tx.hash;

ABOUT

PROTOCOL

INTEGRATIONS

EXAMPLES

LEARN MORE

End-to-end Transaction Example (Ethereum)

Quickstart: minimal working example

React Integration Example

Breaking it down

1. Building the quote request

2. Wallet provider setup

3. Token allowance and approval

4. Transaction execution

​Quickstart: minimal working example

​React Integration Example

​Breaking it down

​1. Building the quote request

​2. Wallet provider setup

​3. Token allowance and approval

​4. Transaction execution

Quickstart: minimal working example

React Integration Example

Breaking it down

1. Building the quote request

2. Wallet provider setup

3. Token allowance and approval

4. Transaction execution