AcrossAcross Developer Documentation
IntroductionGuidesAI AgentsToolsAPI ReferenceChains & Contracts

Build embedded crosschain swap actions with the Swap API

Use the /`swap/approval` API to build embedded crosschain actions (e.g., mint, deposit) that execute on the destination chain immediately after a swap. Define an action with its `target`, `functionSignature`, and `value`. For contract calls, provide an `args[]` array where each parameter can be static or dynamically populated with a token balance by setting `populateDynamically: true` and specifying the `balanceSourceToken`. In this example we will transfer the entire balance of a newly swapped token, call the ERC20 transfer function with a static recipient address and a dynamic amount argument flagged for population.

POST
/swap/approval

Authorization

bearerAuth
AuthorizationBearer <token>

API key for authentication. Request your key at https://t.me/acrosstg.

In: header

Query Parameters

tradeType*string

Defines the type of trade execution strategy used in a swap or bridge request. Each trade type specifies how input and output token amounts are determined and how associated fees are handled. Here are the tradeTypes:

  • exactInput: Use this when you want to bridge or swap a fixed amount of your inputToken. You define the exact quantity of tokens to send, and the system calculates the amount of outputToken you'll receive after all fees are deducted. If your input isn't sufficient to cover the transaction fees, the request will fail.
  • minOutput: Use this when you need to receive at least a certain amount of the outputToken. You set the minimum output you're willing to accept, and the system calculates the necessary input amount, including fees and slippage. Due to price slippage, the final amount you receive will be at least your specified minimum but could be slightly more. This is especially useful for simple swaps without subsequent crosschain actions.
  • exactOutput: Use this when you need to receive a precise amount of the destination token. You specify the exact output you require, and the system calculates the total input needed to guarantee that amount. If market conditions prevent the system from delivering that exact amount, the entire transaction is cancelled, and your funds are refunded. This is recommended for multi-step transactions, like providing an exact amount of an ERC20 token to a minting contract.
Default"exactInput"
Value in"minOutput" | "exactOutput" | "exactInput"
amount*string

Required amount of output token in smallest unit.

inputToken*string

Address of the input token on the origin chain.

outputToken*string

Address of the output token on the destination chain.

originChainId*integer

Chain ID of the origin chain.

destinationChainId*integer

Chain ID of the destination chain.

depositor*string

Address of the depositor initiating the swap.

recipient?string

Address of the account receiving the output token. Defaults to depositor if not provided.

appFee?number

Enables integrators to collect a customizable fee in the output token, sent to a designated address on the destination chain. appFee is expressed in percentage with value ranging between 0 and 1.

appFeeRecipient?string

Address of the account receiving the app fees. Must be defined if you are also defining appFee.

integratorId?string

2-byte hex-string that identifies the integrator. E.g., "0xdead".

refundAddress?string

Address to receive refunds. Defaults to depositor if not provided.

Default"0xDEPOSITOR_ADDRESS"
refundOnOrigin?boolean

For routes that include a destination swap (bridgeableToAny or anyToAny), destination refunds are the default behavior unless refundOnOrigin=true is explicitly set when calling the Swap API. Across determines refund behavior based on the route type (when refundOnOrigin is NOT explicitly set):

  1. B2B or A2B routes:
  • refundOnOrigin defaults to true
  • Refunds occur on the origin chain
  • Destination refunds do not apply here
  1. B2A or A2A routes
  • refundOnOrigin defaults to false
  • Refunds occur on the destination chain

If an explicit refundOnOrigin value is provided, that value is always respected. If a refund occurs, the address that receives the refunded funds is determined using the following priority order: 1. refundAddress (if explicitly specified) 2. recipient (if specified) 3. depositor (fallback) This applies to both origin and destination refunds.

Defaulttrue
slippage?string

Slippage tolerance percentage can be set to auto (default) or a numerical value. Numerical value must be between 0 and 1 representing corresponding percentage. So if you want slippage to be 0.5% , you need to pass 0.005 as the value here). If slippage is auto, the Swap API will select the best slippage intelligently and move ahead with the crosschain swap. If slippage is set to a numerical value, for example 0.01 (1% slippage), it divides this value equally for each leg. This means 0.5% slippage for origin and 0.5% slippage for destination.

Default"auto"
Formatfloat | string
skipOriginTxEstimation?boolean

Used to define whether you want to calculate the transaction details (swap) on origin chain. Defaults to false.

Defaulttrue
strictTradeType?boolean

Used to define whether you want to strictly follow the defined tradeType.Defaults to true.

Defaulttrue
excludeSources?array<>

Used to define the sources you want to exclude from the crosschain swap action. Defaults to an empty array.

Defaulttrue
includeSources?array<>

Used to define the sources you want to include from the crosschain swap action. Defaults to an empty array.

Defaulttrue

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

curl -X POST "https://app.across.to/api/swap/approval?tradeType=minOutput&amount=1000000&inputToken=0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85&outputToken=0x82aF49447D8a07e3bd95BD0d56f35241523fBab1&originChainId=10&destinationChainId=42161&depositor=0xA4d353BBc130cbeF1811f27ac70989F9d568CeAB" \  -H "Content-Type: application/json" \  -d '{    "actions": [      {        "target": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",        "functionSignature": "function transfer(address to, uint256 value)",        "args": [          {            "value": "0x718648C8c531F91b528A7757dD2bE813c3940608",            "populateDynamically": false          },          {            "value": "0",            "populateDynamically": true,            "balanceSourceToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"          }        ],        "value": "0",        "isNativeTransfer": false      }    ]  }'
{
  "crossSwapType": "anyToBridgeable",
  "amountType": "exactInput",
  "approvalTxns": [
    {
      "chainId": 10,
      "to": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "data": "0x095ea7b300000...ffffffffffffffffffffffffff"
    }
  ],
  "checks": {
    "allowance": {
      "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "spender": "0x6f26Bf09B1C792e3228e5467807a900A503c0281",
      "actual": "115792089237316195423570985008687907853269984665640564039457584007913099639935",
      "expected": "1000000"
    },
    "balance": {
      "token": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
      "actual": "7169942",
      "expected": "1000000"
    }
  },
  "steps": {
    "originSwap": {
      "tokenIn": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      },
      "tokenOut": {
        "address": "0x4200000000000000000000000000000000000006",
        "decimals": 18,
        "symbol": "WETH",
        "chainId": 10
      },
      "inputAmount": "1000000",
      "outputAmount": "472306805062946",
      "minOutputAmount": "468764504022050",
      "maxInputAmount": "1000000",
      "swapProvider": {
        "name": "0x",
        "sources": [
          "woofi_v2"
        ]
      },
      "slippage": 0.0075
    },
    "bridge": {
      "inputAmount": "468764504022050",
      "outputAmount": "464434354522974",
      "tokenIn": {
        "address": "0x4200000000000000000000000000000000000006",
        "decimals": 18,
        "symbol": "WETH",
        "chainId": 10
      },
      "tokenOut": {
        "decimals": 18,
        "symbol": "WETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "name": "Wrapped Ether",
        "chainId": 42161
      },
      "fees": {
        "amount": "4330149499076",
        "pct": "9237366442904769",
        "token": {
          "address": "0x4200000000000000000000000000000000000006",
          "decimals": 18,
          "symbol": "WETH",
          "chainId": 10
        },
        "details": {
          "type": "across",
          "relayerCapital": {
            "amount": "46867294561",
            "pct": "99980468145248",
            "token": {
              "address": "0x4200000000000000000000000000000000000006",
              "decimals": 18,
              "symbol": "WETH",
              "chainId": 10
            }
          },
          "destinationGas": {
            "amount": "4260773033213",
            "pct": "9089367895086142",
            "token": {
              "chainId": 42161,
              "address": "0x0000000000000000000000000000000000000000",
              "decimals": 18,
              "symbol": "ETH"
            }
          },
          "lp": {
            "amount": "22509171302",
            "pct": "48018079673379",
            "token": {
              "address": "0x4200000000000000000000000000000000000006",
              "decimals": 18,
              "symbol": "WETH",
              "chainId": 10
            }
          }
        }
      },
      "provider": "across"
    },
    "destinationSwap": {
      "tokenIn": {
        "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
        "decimals": 6,
        "symbol": "USDC",
        "chainId": 42161
      },
      "tokenOut": {
        "decimals": 18,
        "symbol": "ETH",
        "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
        "name": "Ether",
        "chainId": 42161
      },
      "inputAmount": "980662",
      "maxInputAmount": "980662",
      "outputAmount": "263466241499732",
      "minOutputAmount": "260831579075100",
      "swapProvider": {
        "name": "0x",
        "sources": [
          "uniswap_v3"
        ]
      }
    }
  },
  "inputToken": {
    "decimals": 6,
    "symbol": "USDC",
    "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
    "name": "USD Coin",
    "chainId": 10
  },
  "outputToken": {
    "decimals": 18,
    "symbol": "WETH",
    "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
    "name": "Wrapped Ether",
    "chainId": 42161
  },
  "refundToken": {
    "decimals": 18,
    "symbol": "WETH",
    "address": "0x4200000000000000000000000000000000000006",
    "name": "WETH",
    "chainId": 10
  },
  "fees": {
    "total": {
      "amount": "6701",
      "amountUsd": "0.0067",
      "pct": "6701306754817189",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      },
      "details": {
        "type": "total-breakdown",
        "swapImpact": {
          "amount": "-2490",
          "amountUsd": "-0.002490006186373967",
          "pct": "-2490491832281262",
          "token": {
            "decimals": 6,
            "symbol": "USDC",
            "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
            "name": "USD Coin",
            "chainId": 10
          }
        },
        "app": {
          "amount": "0",
          "amountUsd": "0.0",
          "pct": "0",
          "token": {
            "decimals": 18,
            "symbol": "WETH",
            "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "name": "Wrapped Ether",
            "chainId": 42161
          }
        },
        "bridge": {
          "amount": "4330149499076",
          "amountUsd": "0.009190006186373967",
          "pct": "9191798587098451",
          "token": {
            "decimals": 18,
            "symbol": "WETH",
            "address": "0x4200000000000000000000000000000000000006",
            "name": "WETH",
            "chainId": 10
          },
          "details": {
            "type": "across",
            "lp": {
              "amount": "22509171302",
              "amountUsd": "0.000047771889529374",
              "pct": "47781206864712",
              "token": {
                "decimals": 18,
                "symbol": "WETH",
                "address": "0x4200000000000000000000000000000000000006",
                "name": "WETH",
                "chainId": 10
              }
            },
            "relayerCapital": {
              "amount": "46867294561",
              "amountUsd": "0.000099467865265647",
              "pct": "99487265282377",
              "token": {
                "decimals": 18,
                "symbol": "WETH",
                "address": "0x4200000000000000000000000000000000000006",
                "name": "WETH",
                "chainId": 10
              }
            },
            "destinationGas": {
              "amount": "4260773033213",
              "amountUsd": "0.009042766431578945",
              "pct": "9044530114951359",
              "token": {
                "chainId": 42161,
                "address": "0x0000000000000000000000000000000000000000",
                "decimals": 18,
                "symbol": "ETH",
                "name": "Ether"
              }
            }
          }
        }
      }
    },
    "totalMax": {
      "amount": "14102",
      "amountUsd": "0.0141",
      "pct": "14102750036257069",
      "token": {
        "decimals": 6,
        "symbol": "USDC",
        "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "name": "USD Coin",
        "chainId": 10
      },
      "details": {
        "type": "max-total-breakdown",
        "maxSwapImpact": {
          "amount": "4910",
          "amountUsd": "0.004909993813626033",
          "pct": "4910951449158618",
          "token": {
            "decimals": 6,
            "symbol": "USDC",
            "address": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
            "name": "USD Coin",
            "chainId": 10
          }
        },
        "app": {
          "amount": "0",
          "amountUsd": "0.0",
          "pct": "0",
          "token": {
            "decimals": 18,
            "symbol": "WETH",
            "address": "0x82aF49447D8a07e3bd95BD0d56f35241523fBab1",
            "name": "Wrapped Ether",
            "chainId": 42161
          }
        },
        "bridge": {
          "amount": "4330149499076",
          "amountUsd": "0.009190006186373967",
          "pct": "9191798587098451",
          "token": {
            "decimals": 18,
            "symbol": "WETH",
            "address": "0x4200000000000000000000000000000000000006",
            "name": "WETH",
            "chainId": 10
          },
          "details": {
            "type": "across",
            "lp": {
              "amount": "22509171302",
              "amountUsd": "0.000047771889529374",
              "pct": "47781206864712",
              "token": {
                "decimals": 18,
                "symbol": "WETH",
                "address": "0x4200000000000000000000000000000000000006",
                "name": "WETH",
                "chainId": 10
              }
            },
            "relayerCapital": {
              "amount": "46867294561",
              "amountUsd": "0.000099467865265647",
              "pct": "99487265282377",
              "token": {
                "decimals": 18,
                "symbol": "WETH",
                "address": "0x4200000000000000000000000000000000000006",
                "name": "WETH",
                "chainId": 10
              }
            },
            "destinationGas": {
              "amount": "4260773033213",
              "amountUsd": "0.009042766431578945",
              "pct": "9044530114951359",
              "token": {
                "chainId": 42161,
                "address": "0x0000000000000000000000000000000000000000",
                "decimals": 18,
                "symbol": "ETH",
                "name": "Ether"
              }
            }
          }
        }
      }
    },
    "originGas": {
      "amount": "626037662500",
      "amountUsd": "0.001328658512253625",
      "token": {
        "chainId": 10,
        "address": "0x0000000000000000000000000000000000000000",
        "decimals": 18,
        "symbol": "ETH",
        "name": "Ether"
      }
    }
  },
  "inputAmount": "1000000",
  "maxInputAmount": "1000000",
  "expectedOutputAmount": "467917612181896",
  "minOutputAmount": "464434354522974",
  "expectedFillTime": 2,
  "swapTx": {
    "simulationSuccess": true,
    "chainId": 10,
    "to": "0x89415a82d909a7238d69094C3Dd1dCC1aCbDa85C",
    "data": "0x110560ad0000000000000000000000000000000000000000000000000000000000000020...",
    "gas": "571750",
    "maxFeePerGas": "1094950",
    "maxPriorityFeePerGas": "1000000"
  },
  "quoteExpiryTimestamp": 1770679043,
  "id": "vqhfb-1770675636494-01dc8983f2fc"
}
{
  "type": "AcrossApiError",
  "code": "INVALID_PARAM",
  "status": 400,
  "message": "Invalid parameter at path 'depositor'. Expected type 'validAddress'",
  "id": "dbsft-1756414126692-6a64b1802b70"
}
{
  "type": "AcrossApiError",
  "code": "INVALID_PARAM",
  "status": 400,
  "message": "Relayer Address (0x00000000000000000000000007ae8551be970cb1cca11dd7a11f47ae82e70e67) doesn't have enough funds to support this deposit; for help, please reach out to https://discord.across.to",
  "id": "dbsft-1756414126692-6a64b1802b70"
}

Get swap approval data GET

Returns data required to execute a crosschain swap. If the input token requires approval, `approvalTxns` will be included in the response.

Get supported chains for swap operations GET

Returns a list of all supported blockchains that support crosschain swaps on Across Protocol.