Execute Swap

POST

execute

swap

curl --request POST \
  --url https://api.relay.link/execute/swap \
  --header 'Content-Type: application/json' \
  --data '{
  "user": "<string>",
  "recipient": "<string>",
  "originChainId": 123,
  "destinationChainId": 123,
  "originCurrency": "<string>",
  "destinationCurrency": "<string>",
  "amount": "<string>",
  "tradeType": "EXACT_INPUT",
  "txs": [
    {
      "to": "<string>",
      "value": "<string>",
      "data": "<string>"
    }
  ],
  "source": "<string>",
  "refundTo": "<string>",
  "refundOnOrigin": true,
  "useForwarder": true,
  "useExternalLiquidity": true,
  "usePermit": true,
  "slippageTolerance": "<string>",
  "appFees": [
    {
      "recipient": "<string>",
      "fee": "<string>"
    }
  ]
}'

{
  "steps": [
    {
      "id": "deposit",
      "action": "Confirm transaction in your wallet",
      "description": "Depositing funds to the relayer to execute the swap for USDC",
      "kind": "transaction",
      "requestId": "0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
      "items": [
        {
          "status": "incomplete",
          "data": {
            "from": "0x0CccD55A5Ac261Ea29136831eeaA93bfE07f5Db6",
            "to": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
            "data": "0x00fad611",
            "value": "1000000000000000000",
            "maxFeePerGas": "12205661344",
            "maxPriorityFeePerGas": "2037863396",
            "chainId": 1
          },
          "check": {
            "endpoint": "/intents/status?requestId=0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
            "method": "GET"
          }
        }
      ]
    }
  ],
  "fees": {
    "gas": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayer": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayerGas": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayerService": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "app": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    }
  },
  "breakdown": [
    {
      "value": "1000000000000000000",
      "timeEstimate": 10
    }
  ],
  "balances": {
    "userBalance": "<string>",
    "requiredToSolve": "<string>"
  },
  "details": {
    "operation": "<string>",
    "timeEstimate": 123,
    "userBalance": "<string>",
    "sender": "<string>",
    "recipient": "<string>",
    "currencyIn": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "currencyOut": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "totalImpact": {
      "usd": "<string>",
      "percent": "<string>"
    },
    "swapImpact": {
      "usd": "<string>",
      "percent": "<string>"
    },
    "rate": "<string>",
    "slippageTolerance": {
      "origin": {
        "usd": "<string>",
        "value": "<string>",
        "percent": "<string>"
      },
      "destination": {
        "usd": "<string>",
        "value": "<string>",
        "percent": "<string>"
      }
    }
  }
}

This API has been replaced by the Get Quote API, which supports bridging, swapping and calling through a single unified API.

We recommend using the SDK over our APIs. The SDK will iterate the steps and return useful callback information. The APIs will require iterating through the steps manually.
Get started with the Relay SDK here.

Body

application/json

user

string

required

Address that is depositing funds on the origin chain and submitting transactions or signatures

originChainId

number

required

destinationChainId

number

required

originCurrency

string

required

destinationCurrency

string

required

amount

string

required

Amount to swap as the base amount (can be switched to exact input/output using the dedicated flag), denoted in the smallest unit of the specified currency (e.g., wei for ETH)

tradeType

enum<string>

required

Whether to use the amount as the output or the input for the basis of the swap

Available options:

EXACT_INPUT,

EXACT_OUTPUT,

EXPECTED_OUTPUT

recipient

string

Address that is receiving the funds on the destination chain, if not specified then this will default to the user address

txs

object[]

source

string

refundTo

string

Address to send the refund to in the case of failure, if not specified then the recipient address or user address is used

refundOnOrigin

boolean

Always refund on the origin chain in case of any issues

useForwarder

boolean

default:

true

Enable this to route payments via a forwarder contract. This contract will emit an event when receiving payments before forwarding to the solver. This is needed when depositing from a smart contract as the payment will be an internal transaction and detecting such a transaction requires obtaining the transaction traces.

useExternalLiquidity

boolean

Enable this to use canonical+ bridging, trading speed for more liquidity

usePermit

boolean

Enable this to use permit (eip3009) when bridging, only works on supported currency such as usdc

slippageTolerance

string

Slippage tolerance for the swap, if not specified then the slippage tolerance is automatically calculated to avoid front-running. This value is in basis points (1/100th of a percent), e.g. 50 for 0.5% slippage

appFees

object[]

Response

200

application/json

Default Response

steps

object[]

An array of steps detailing what needs to be done to bridge, steps includes multiple items of the same kind (signature, transaction, etc)

fees

object

fees.gas

object

Origin chain gas fee

fees.relayer

object

Combination of the relayerGas and relayerService to give you the full relayer fee

fees.relayerGas

object

Destination chain gas fee

fees.relayerService

object

Fees paid to the relay solver, note that this value can be negative (which represents network rewards for moving in a direction that optimizes liquidity distribution)

fees.app

object

Fees paid to the app. Currency will be the same as the relayer fee currency. This needs to be claimed later by the app owner and is not immediately distributed to the app

breakdown

object[]

balances

object

details

object

A summary of the swap and what the user should expect to happen given an input

details.operation

string

The operation that will be performed, possible options are send, swap, wrap, unwrap, bridge

details.timeEstimate

number

Estimated swap time in seconds

details.userBalance

string

The user's balance in the given currency on the origin chain

details.sender

string

The address that deposited the funds

details.recipient

string

The address that will be receiving the swap output

details.currencyIn

object

details.currencyOut

object

details.totalImpact

object

The difference between the input and output values, including fees

details.swapImpact

object

The impact of the swap, not factoring in fees

details.rate

string

The swap rate which is equal to 1 input unit in the output unit, e.g. 1 USDC -> x ETH. This value can fluctuate based on gas and fees.

details.slippageTolerance

object

Execute Bridge Get Execution Status

curl --request POST \
  --url https://api.relay.link/execute/swap \
  --header 'Content-Type: application/json' \
  --data '{
  "user": "<string>",
  "recipient": "<string>",
  "originChainId": 123,
  "destinationChainId": 123,
  "originCurrency": "<string>",
  "destinationCurrency": "<string>",
  "amount": "<string>",
  "tradeType": "EXACT_INPUT",
  "txs": [
    {
      "to": "<string>",
      "value": "<string>",
      "data": "<string>"
    }
  ],
  "source": "<string>",
  "refundTo": "<string>",
  "refundOnOrigin": true,
  "useForwarder": true,
  "useExternalLiquidity": true,
  "usePermit": true,
  "slippageTolerance": "<string>",
  "appFees": [
    {
      "recipient": "<string>",
      "fee": "<string>"
    }
  ]
}'

{
  "steps": [
    {
      "id": "deposit",
      "action": "Confirm transaction in your wallet",
      "description": "Depositing funds to the relayer to execute the swap for USDC",
      "kind": "transaction",
      "requestId": "0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
      "items": [
        {
          "status": "incomplete",
          "data": {
            "from": "0x0CccD55A5Ac261Ea29136831eeaA93bfE07f5Db6",
            "to": "0xf70da97812cb96acdf810712aa562db8dfa3dbef",
            "data": "0x00fad611",
            "value": "1000000000000000000",
            "maxFeePerGas": "12205661344",
            "maxPriorityFeePerGas": "2037863396",
            "chainId": 1
          },
          "check": {
            "endpoint": "/intents/status?requestId=0x92b99e6e1ee1deeb9531b5ad7f87091b3d71254b3176de9e8b5f6c6d0bd3a331",
            "method": "GET"
          }
        }
      ]
    }
  ],
  "fees": {
    "gas": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayer": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayerGas": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "relayerService": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "app": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    }
  },
  "breakdown": [
    {
      "value": "1000000000000000000",
      "timeEstimate": 10
    }
  ],
  "balances": {
    "userBalance": "<string>",
    "requiredToSolve": "<string>"
  },
  "details": {
    "operation": "<string>",
    "timeEstimate": 123,
    "userBalance": "<string>",
    "sender": "<string>",
    "recipient": "<string>",
    "currencyIn": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "currencyOut": {
      "currency": {
        "chainId": 8453,
        "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
        "symbol": "USDC",
        "name": "USD Coin",
        "decimals": 6,
        "metadata": {
          "logoURI": "https://ethereum-optimism.github.io/data/USDC/logo.png",
          "verified": false,
          "isNative": false
        }
      },
      "amount": "30754920",
      "amountFormatted": "30.75492",
      "amountUsd": "30.901612",
      "minimumAmount": "30454920"
    },
    "totalImpact": {
      "usd": "<string>",
      "percent": "<string>"
    },
    "swapImpact": {
      "usd": "<string>",
      "percent": "<string>"
    },
    "rate": "<string>",
    "slippageTolerance": {
      "origin": {
        "usd": "<string>",
        "value": "<string>",
        "percent": "<string>"
      },
      "destination": {
        "usd": "<string>",
        "value": "<string>",
        "percent": "<string>"
      }
    }
  }
}

API Reference

Body

Response