For Agents

AI Agent integration

Fly Trade EVM Swap API — Agent Reference

Overview

Base URL: https://api.fly.trade

Execute a token swap on EVM networks in 3 steps:

1. GET /aggregator/quote → receive quoteId + pricing

2. GET /aggregator/transaction → receive transaction payload

3. Sign and submit transaction to the network

Shortcut: Use GET /aggregator/quote/transaction to get both quote and transaction in one call (no gas estimation).

Decision Tree for Agent Use

Want to swap tokens?
│
├─ Standard swap (user pays gas in native token)
│   ├─ Need gas estimate?  → Step 1 (quote) + Step 2 (transaction, estimateGas=true) + Step 3
│   └─ No gas estimate needed? → Combined /quote/transaction + Step 3
│
└─ Calling from a smart contract?
    └─ GET /quote/transaction (estimateGas=false, fromAddress=CONTRACT) → forward data as calldata

---

Supported Networks

Use the network string (not chain ID) in all requests.

network value	Chain
ethereum	Ethereum Mainnet
polygon	Polygon
bsc	BNB Smart Chain
arbitrum	Arbitrum One
optimism	Optimism
base	Base
avalanche	Avalanche C-Chain
blast	Blast
manta	Manta Pacific
scroll	Scroll
fantom	Fantom
polygonzk	Polygon zkEVM
zksync	zkSync Era
linea	Linea
sonic	Sonic
megaeth	MegaETH
fogo	Fogo
stable	Stable
plasma	Plasma
monad	Monad
hyperevm	HyperEVM
eclipse	Eclipse
unichain	Unichain
berachain	Berachain
abstract	Abstract
ink	Ink
taiko	Taiko
metis	Metis
solana	Solana
morph	Morph
zerogravity	0g
katana	Katana
tempo	Tempo
telos	Telos
pharos	Pharos

Full list: GET /token-manager/networks or check Swagger at https://api.fly.trade/swagger.

---

These 5 endpoints cover most agent use cases:

Step 1 — Get Quote

GET /aggregator/quote

Fetches a quote estimating the output amount you'll receive for swapping a given input asset. Use this to preview the exchange rate, fees, and expected output before committing to a transaction.

Required Parameters

Parameter	Type	Description
network	string	Network name (e.g. ethereum)
fromTokenAddress	string	The token address of the token to sell. Use 0x0000000000000000000000000000000000000000 for native token (ETH/MATIC/BNB)
toTokenAddress	string	Token to buy. Use 0x0000000000000000000000000000000000000000 for native token (ETH/MATIC/BNB)
sellAmount	string	The amount of the token to sell.
slippage	number	Max slippage. 0.005 = 0.5%, 0.01 = 1%
fromAddress	string	Wallet address sending the swap
toAddress	string	Wallet address receiving tokens
gasless	boolean	Always set gasless: false. This ensures the user pays gas in the native token. Gasless transactions are deprecated and will be removed in a future release.

Optional Parameters

Parameter	Type	Description
affiliateAddress	string	Address to receive affiliate fee
affiliateFee	number	Fee percentage. 0.01 = 1%. Deducted from fromToken

Example Request

GET https://api.fly.trade/aggregator/quote?network=ethereum&fromTokenAddress=0x0000000000000000000000000000000000000000&toTokenAddress=0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48&fromAddress=0xff270dc360ef80314c7d6b2564fe76eaf3979b1a&toAddress=0xff270dc360ef80314c7d6b2564fe76eaf3979b1a&sellAmount=1000000000000000000&slippage=0.005&gasless=false```

Response Schema (Standard Swap)

{
  "id": "8de05661-09d6-4b82-ab63-1e32ee1fa297",   // ← save as quoteId
  "amountOut": "1956398549",                        // expected output in smallest unit
  "targetAddress": "0xa6e941eab67569ca4522f70d343714ff51d571c4",  // router address (use for ERC-20 approval)
  "fees": [
    { "type": "gas", "value": "0.0150" }
  ],
  "resourceEstimate": {
    "gasLimit": "191157"
  }
}

Critical Constraints

• Quote expires in 5 minutes. After expiry, the quoteId is invalid. Fetch a new quote.

• Single-use. Each quoteId can only be used once with /aggregator/transaction. If consumed or expired, fetch a new quote.

• ERC-20 approval required before executing. The spender is targetAddress from the quote response.

---

Step 2 — Get Transaction Payload

GET /aggregator/transaction

Required Parameters

Parameter	Type	Description
quoteId	string	The id value returned from Step 1

Optional Parameters

Parameter	Type	Default	Description
estimateGas	boolean	true	When true, validates token approval and balance before returning. Fails with "Couldn't estimate gas" if checks fail. Set to false for contract integrations.

Example Request

GET https://api.fly.trade/aggregator/transaction?quoteId=8de05661-09d6-4b82-ab63-1e32ee1fa297

Response Schema

{
  "from": "0xff270dc360ef80314c7d6b2564fe76eaf3979b1a",
  "to": "0xa6e941eab67569ca4522f70d343714ff51d571c4",   // router contract
  "data": "0x73fc4457...",                               // encoded calldata
  "chainId": 1,
  "type": 2,                                             // EIP-1559 (type 2) or legacy (type 0)
  "gasLimit": "314086",
  "maxFeePerGas": "228922087",                           // present for EIP-1559 chains
  "maxPriorityFeePerGas": "190605439",                   // present for EIP-1559 chains
  "value": "10000000000000000"                           // ETH value in wei (0 for ERC-20 swaps)
}

Note: Some chains return legacy format with gasPrice instead of maxFeePerGas/maxPriorityFeePerGas. Ensure your signer/library handles both.

---

Alternative: Combined Quote + Transaction (Single Request)

GET /aggregator/quote/transaction

Accepts all parameters from /aggregator/quote. fromAddress and toAddress are required. Gas is not estimated.

Example Request

GET https://api.fly.trade/aggregator/quote/transaction?network=base&fromTokenAddress=1&toTokenAddress=2&sellAmount=3&slippage=1&gasless=false&toAddress=111&fromAddress=111```

Response Schema

{
  "quote": {
    "id": "...",
    "amountOut": "...",
    "targetAddress": "...",
    "fees": [...],
    "resourceEstimate": { "gasLimit": "..." }
  },
  "transaction": {
    "from": "...",
    "to": "...",
    "data": "...",
    "chainId": 1,
    "type": 2,
    "gasLimit": "...",
    "maxFeePerGas": "...",
    "maxPriorityFeePerGas": "...",
    "value": "..."
  }
}

---

Step 3 — Execute the Transaction

Submit the transaction object from Step 2 directly to the network using any EVM-compatible library.

TypeScript (ethers.js):

const tx = await signer.sendTransaction({
  to: transaction.to,
  data: transaction.data,
  value: transaction.value,
  gasLimit: transaction.gasLimit,
  // For EIP-1559:
  maxFeePerGas: transaction.maxFeePerGas,
  maxPriorityFeePerGas: transaction.maxPriorityFeePerGas,
  // For legacy chains, use gasPrice instead
});
const receipt = await tx.wait();

---

ERC-20 Token Approval

Before swapping an ERC-20 token, the fromAddress must approve the router contract (targetAddress from the quote) to spend the token.

const token = new ethers.Contract(fromTokenAddress, [
  'function allowance(address owner, address spender) view returns (uint256)',
  'function approve(address spender, uint256 amount) returns (bool)'
], signer);

const allowance = await token.allowance(userAddress, routerAddress);
if (allowance.lt(sellAmount)) {
  const approveTx = await token.approve(routerAddress, ethers.constants.MaxUint256);
  await approveTx.wait();
}

---

Smart Contract Integration

When calling from a contract, always set estimateGas=false or use the combined /aggregator/quote/transaction endpoint with fromAddress set to your contract address.

// Get transaction data targeting your contract as sender
const url = new URL('https://api.fly.trade/aggregator/quote/transaction');
url.searchParams.set('fromAddress', CONTRACT_ADDRESS);
url.searchParams.set('estimateGas', 'false');
// ... other params

const { transaction } = await fetch(url.toString()).then(r => r.json());

// Pass transaction.data as calldata to your contract
await mySwapContract.executeSwap(fromToken, amountIn, transaction.data, { value: 0 });

Contract requirements:

• Approve the Fly router for ERC-20 tokens before calling

• Forward transaction.data as calldata to the router (targetAddress)

• Forward the correct msg.value for native token swaps