# For Agents ## 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 ````bash 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) ```json { "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 ```bash GET https://api.fly.trade/aggregator/transaction?quoteId=8de05661-09d6-4b82-ab63-1e32ee1fa297 ``` #### Response Schema ```json { "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 ````bash 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 ```json { "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):** ```typescript 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. ```typescript 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**. ```typescript // 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 --- # 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: ``` GET https://docs.fly.trade/developers/for-agents.md?ask= ``` 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.