How to execute a swap

In this section, you'll learn how to execute a token swap using the transaction data generated from a previously obtained quote.

Prerequisites

• How to Get a Quote

• API key for authentication

• A valid quote from the /swap/quote endpoint

Overview

After obtaining a quote, you can execute the swap by generating the necessary transaction data (bytecode) and submitting it to the blockchain. The DeFrame API handles the complexity of preparing the transaction data for different providers and swap types.

Authentication

All requests require an API key in the headers:

x-api-key: YOUR_API_KEY

Executing a Swap

Endpoint

POST https://client.deframe.io/v1/swap/bytecode

Request Body

Parameter	Type	Required	Description
destinationAddress	string	✅	The destination wallet address to receive the swapped tokens
quote	object	✅	The quote object obtained from the /swap/quote endpoint
walletAddress	string	❌	User's wallet address for provider-specific logic
decimalsIn	number	❌	Number of decimals for the input token

Example Request

POST /swap/bytecode
{
  "destinationAddress": "0x1234567890123456789012345678901234567890",
  "quote": {
    "fromChain": {
      "chainId": "1",
      "name": "Ethereum"
    },
    "toChain": {
      "chainId": "1",
      "name": "Ethereum"
    },
    "expectedAmountOut": "1000000000000000000",
    "provider": "1inch",
    "tokenIn": "0xA0b86a33E6441b8c4C8C1C1B8c4C8C1C1B8c4C8C1",
    "tokenOut": "0xB0b86a33E6441b8c4C8C1C1B8c4C8C1C1B8c4C8C1",
    "amountIn": "500000000000000000"
  },
  "walletAddress": "0x1234567890123456789012345678901234567890",
  "decimalsIn": 18
}

Response Format

The API returns comprehensive transaction data:

{
  "type": "intra-chain-evm",
  "provider": "1inch",
  "chainId": "polygon",
  "transactionData": {
    "to": "0x111111125421ca6dc452d289314280a0f8842a65",
    "data": "0x07ed23790000000000000000000000001380f2f57553ada04b31ee7b1e039e496939db3d000000000000000000000000b5c064f955d8e7f38fe0460c556a72987494ee170000000000000000000000003c499c542cef5e3811e1192ce70d8cc03d5c33590000000000000000000000001380f2f57553ada04b31ee7b1e039e496939db3d000000000000000000000000dae3a7024062ddfd36e636310e277b1c45461fea0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000000000000005a710000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001620000000000000000000000000000000000000000000001440000dd00004e00a0744c8c09b5c064f955d8e7f38fe0460c556a72987494ee1790cbe4bdd538d6e9b379bff5fe72c3d67a521de5000000000000000000000000000000000000000000000000000aa87bee5380000c20b5c064f955d8e7f38fe0460c556a72987494ee17f3eb2f17eafbf35e92c965a954c6e7693187057d6ae4071138002dc6c0f3eb2f17eafbf35e92c965a954c6e7693187057d6d9e8dbb2779853db00418d4dcf96f3987cfc9d200000000000000000000000000000000000000000000000001c5ba2299a3bbe1b5c064f955d8e7f38fe0460c556a72987494ee1700206ae40711b8002dc6c06d9e8dbb2779853db00418d4dcf96f3987cfc9d2111111125421ca6dc452d289314280a0f8842a650000000000000000000000000000000000000000000000000000000000005a710d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000000000000000000000000000000000bffdec3c",
    "value": "0",
    "gasLimit": null
  },
  "approveData": {
    "to": "0xb5c064f955d8e7f38fe0460c556a72987494ee17",
    "data": "0x095ea7b3000000000000000000000000111111125421ca6dc452d289314280a0f8842a6500000000000000000000000000000000000000000000d3c21bcecceda1000000",
    "value": "0"
  },
  "swapDetails": {
    "fromChain": "polygon",
    "toChain": "polygon",
    "fromToken": {
      "contract": "0xb5c064f955d8e7f38fe0460c556a72987494ee17",
      "symbol": "QUICK",
      "decimals": 18,
      "amount": "1000000000000000000",
      "chainId": 137
    },
    "toToken": {
      "contract": "0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
      "symbol": "USDC",
      "decimals": 6,
      "amount": "23315",
      "chainId": 137
    },
    "effectiveAmountIn": "1000000000000000000",
    "expectedAmountOut": "23315",
    "destinationAddress": "0xdae3A7024062DdFD36e636310e277b1c45461Fea"
  },
  "rawSwapData": {
    "dstAmount": "23387",
    "tx": {
      "from": "0xdae3a7024062ddfd36e636310e277b1c45461fea",
      "to": "0x111111125421ca6dc452d289314280a0f8842a65",
      "data": "0x07ed23790000000000000000000000001380f2f57553ada04b31ee7b1e039e496939db3d000000000000000000000000b5c064f955d8e7f38fe0460c556a72987494ee170000000000000000000000003c499c542cef5e3811e1192ce70d8cc03d5c33590000000000000000000000001380f2f57553ada04b31ee7b1e039e496939db3d000000000000000000000000dae3a7024062ddfd36e636310e277b1c45461fea0000000000000000000000000000000000000000000000000de0b6b3a76400000000000000000000000000000000000000000000000000000000000000005a710000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000012000000000000000000000000000000000000000000000000000000000000001620000000000000000000000000000000000000000000001440000dd00004e00a0744c8c09b5c064f955d8e7f38fe0460c556a72987494ee1790cbe4bdd538d6e9b379bff5fe72c3d67a521de5000000000000000000000000000000000000000000000000000aa87bee5380000c20b5c064f955d8e7f38fe0460c556a72987494ee17f3eb2f17eafbf35e92c965a954c6e7693187057d6ae4071138002dc6c0f3eb2f17eafbf35e92c965a954c6e7693187057d6d9e8dbb2779853db00418d4dcf96f3987cfc9d200000000000000000000000000000000000000000000000001c5ba2299a3bbe1b5c064f955d8e7f38fe0460c556a72987494ee1700206ae40711b8002dc6c06d9e8dbb2779853db00418d4dcf96f3987cfc9d2111111125421ca6dc452d289314280a0f8842a650000000000000000000000000000000000000000000000000000000000005a710d500b1d8e8ef31e21c99d1db9a6444d3adf1270000000000000000000000000000000000000000000000000000000000000bffdec3c",
      "value": "0",
      "gas": 0,
      "gasPrice": "130000000025"
    }
  },
  "message": "Dados da transação preparados."
}

Response Fields

• type: Type of swap (e.g., "intra-chain-evm")

• provider: Name of the swap provider used

• chainId: Chain ID where the transaction should be executed

• transactionData: Main transaction data for the swap (to, data, value, gasLimit)

• approveData: Token approval transaction data (if required)

• swapDetails: Detailed information about the swap including token details and amounts

• rawSwapData: Raw provider-specific swap data including the complete transaction object

Swap Types

The endpoint automatically detects the swap type based on the quote:

• Intra-chain Swap: When quote.fromChain equals quote.toChain

• Cross-chain Swap: When quote.fromChain differs from quote.toChain

Transaction Execution

You'll need to sign and submit the transaction data to the blockchain. This happens on your end - we don't touch your funds, custody remains yours.

Here's a basic example using ethers.js:

import { ethers } from 'ethers';

// 1. Create a provider
const provider = new ethers.providers.JsonRpcProvider('YOUR_RPC_URL');

// 2. Create a signer (using your preferred wallet)
const signer = new ethers.Wallet('YOUR_PRIVATE_KEY', provider);

// 3. Execute the transaction
const tx = await signer.sendTransaction({
  to: response.transactionData.to,
  data: response.transactionData.data,
  value: response.transactionData.value,
  gasLimit: response.transactionData.gasLimit
});

// 4. Wait for confirmation
await tx.wait();

Error Handling

The API returns appropriate error messages for:

• Missing required parameters

• Invalid quote object (missing provider information)

• Provider not found for the specified quote

• Provider-specific errors during transaction preparation

Example Error Response:

{
  "error": "Invalid quote provided. Quote must include provider information."
}

Workflow

1. Get Quote: First, obtain a swap quote using the GET /swap/quote endpoint

2. Execute Swap: Use the quote in this endpoint to generate transaction data

3. Submit Transaction: Use the returned transaction data to execute the swap on the blockchain

Next Steps

After executing the swap, you can:

• Get Another Quote