EVM Swap Integration Guide
How to execute same-chain swaps on EVM networks using Fly Trade's APIs
EVM Swap Integration Guide
This guide shows how to execute a swap on EVM networks (Ethereum, Polygon, BSC, Arbitrum, etc.) using Fly Trade's API in 3 steps:
Get a quote (pricing + route + constraints)
Fetch transaction payload with the quote ID
Sign and send the transaction to the network
Prerequisites
An EVM RPC connection (Infura, Alchemy, QuickNode, or self-hosted node)
A wallet that can sign EVM transactions (MetaMask, WalletConnect, ethers.js Signer, or backend private key)
Sufficient balance of the tokens you want to swap and their token contract addresses
How the Flow Works
The high-level swap flow is:
Call
/aggregator/quoteto receive aquoteId, estimated output amount, and swap detailsCall
/aggregator/transactionwith thequoteIdto receive the transaction data (to, data, value, gas parameters)Sign the transaction with the user's wallet
Send the signed transaction to the network
Wait for confirmation
Alternative: Instead of calling quote and transaction separately, you can use the /aggregator/quote/transaction endpoint to get both in a single request. Note that this combined endpoint does not provide gas estimation.
Step 1 β Get a Quote
Endpoint:
Method:
GETPath:
/aggregator/quote
Required Parameters:
network
Network name (e.g., ethereum, polygon, bsc, arbitrum, base). See the network dropdown on Swagger for all supported network names
fromTokenAddress
Token contract address to swap from. Use 0x0000000000000000000000000000000000000000 for native token (ETH/MATIC/BNB)
toTokenAddress
Token contract address to swap to. Use 0x0000000000000000000000000000000000000000 for native token
sellAmount
Amount in smallest unit (wei). For 1 ETH write 1000000000000000000
slippage
Allowed slippage (e.g., 0.005 for 0.5%, 0.01 for 1%)
fromAddress
Wallet address initiating the swap
toAddress
Wallet address receiving the swapped tokens
gasless
Must always be set to false. Gasless transactions are not supported β setting this to true will cause the quote to fail
Optional Parameters
Affiliate Fee:
affiliateAddress: Address to receive affiliate feesaffiliateFee: The fee percentage. For example: 1% = 0.01
Affiliate fees are deducted from the fromTokenAddress amount and sent to the specified address.
Example Request:
Example Response:
Save the id as quoteId for Step 2.
Important Quote Constraints:
Quote Expiry: Each quote has a 5-minute expiration window. After 5 minutes, the quoteId becomes invalid and you will not be able to fetch the transaction payload. If your quote has expired, you must request a fresh quote before proceeding.
Single-Use Quotes: Each quote can only be used to fetch the transaction payload once. After successfully calling /aggregator/transaction with a quoteId, that quote is consumed and cannot be reused. If you need to execute another swap or retry, you must fetch a new quote.
Step 2 β Get Transaction Payload
Endpoint:
Method:
GETPath:
/aggregator/transaction
Required Parameters:
quoteId
The quote id returned from Step 1
Optional Parameters:
estimateGas
Whether to estimate gas when building the transaction. If true, ensures token approval and balance checks are performed. If gas estimation fails, returns error "Couldn't estimate gas"
true
Important: When estimateGas=true, you must have:
Sufficient token approval for the router contract (for ERC-20 swaps)
Enough token balance for the swap
Otherwise, the endpoint will return an error and fail to generate the transaction
Example Request:
Example Response:
Alternative: Combined Quote + Transaction Endpoint
For faster integration, you can fetch both quote and transaction data in a single request.
Endpoint:
Method:
GETPath:
/aggregator/quote/transaction
Parameters:
Accepts all parameters from the /aggregator/quote endpoint (network, fromTokenAddress, toTokenAddress, sellAmount, slippage, fromAddress, toAddress). Always set gasless=false.
Note: fromAddress and toAddress are required for this endpoint and it doesn't estimate gas.
Example Request:
Example Response:
Returns both quote data and transaction payload in one response:
Updating Amount In (Optional)
After fetching transaction data from /aggregator/transaction or /aggregator/quote/transaction, you can dynamically override the amountIn before executing the transaction. This is useful when your integration manages token balances or allowances at execution time rather than at quote time.
Two Modes:
Specify an exact amount β Pass any non-zero
uint256value to set a preciseamountIn.Use balance or allowance (whichever is lower) β Pass
0as theamountIn. The contract will automatically usemin(balance, allowance)at execution time.
How It Works:
The DexAggregator contract exposes a pure helper function updateAmountIn. You pass it the raw transaction data bytes returned by the API along with your desired amountIn, and it returns adjusted calldata ready to execute.
TypeScript Example:
Step 3 β Execute the Swap Transaction
Once you have the transaction payload (from Step 2 or the combined endpoint), you can execute it using your preferred web3 library.
Important: Depending on the blockchain, the transaction response may use EIP-1559 format with maxFeePerGas and maxPriorityFeePerGas (if the chain supports EIP-1559) or legacy format with gasPrice. Make sure your wallet/library supports both transaction types.
Integration Examples
Example 1: Frontend Integration (React + Ethers.js)
Example for integrating swaps in a React frontend application:
Example 2: Smart Contract Integration
If you're building a smart contract that needs to execute swaps, here's how to integrate:
Solidity Contract Example:
Off-chain Script to Call Contract:
Important Notes for Contract Integration:
Set
estimateGas=falsewhen getting transaction data for contract callsThe contract must approve the Fly router before swapping ERC-20 tokens
Pass the transaction data from Fly Trade API directly to the router as calldata
Network Support
Fly Trade supports swaps on multiple EVM networks. You must use the network name (not chain ID) in API requests:
For the complete and up-to-date list of supported network names, refer to the network dropdown in our Swagger documentation for aggregator/quote endpoint or get it from /token-manager/networks endpoint.
Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the ask query parameter:
The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
Last updated