Across Docs

Destination actions

Run contract calls on the destination chain with the bridged funds, in the same transaction as the fill.

Destination actions let one transfer do more than deliver tokens. Add destinationActions to the quote and Across runs your calls on the destination chain with the funds that arrived, in the same transaction as the fill: supply USDC to Aave, wrap a token, deposit into a vault, or pay a contract.

EVM to EVM. Destination actions are available on transfers from an EVM chain to an EVM chain. Destination actions involving Solana are not available yet.

How it works

  1. Describe the calls as steps on the quote request.
  2. Execute the quote as usual.
  3. Track the transfer, and read whether the actions completed from its status.reason.

Quote with destination actions

Below, 5 USDC goes from Arbitrum to Base and is supplied to Aave in the same transaction as the fill. The first step approves the Aave Pool to take the USDC; the second calls supply with the amount that arrived.

1-quote.ts
const BASE_URL = "https://api.across.to";
const API_KEY = process.env.ACROSS_API_KEY;

const USDC_BASE = "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
const AAVE_POOL_BASE = "0xA238Dd80C259a72e81d7e4664a9801593F98d1c5";

const res = await fetch(`${BASE_URL}/v1/quotes`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    origin: {
      token: { chainId: 42161, address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
      amount: "5000000", // 5 USDC
      depositor: "0xYourWalletAddress",
    },
    destination: {
      token: { chainId: 8453, address: USDC_BASE },
      recipient: "0xYourWalletAddress",
    },
    destinationActions: {
      steps: [
        {
          kind: "approve",
          token: USDC_BASE,
          spender: AAVE_POOL_BASE,
          populateDynamically: true,
        },
        {
          kind: "function-call",
          target: AAVE_POOL_BASE,
          functionSignature: "supply(address,uint256,address,uint16)",
          args: [
            { value: USDC_BASE },
            { populateDynamically: true, balanceSourceToken: USDC_BASE },
            { value: "0xYourWalletAddress" }, // onBehalfOf: receives the aTokens
            { value: 0 },
          ],
        },
      ],
      onFailure: { action: "revert" },
    },
  }),
});

const quote = await res.json();

Your steps decide where the funds end up. With steps present, the output is not sent to destination.recipient: the last step has to deliver the final asset. Above, that is Aave's onBehalfOf argument.

Execute as usual

Follow the quote's nextActions exactly as you would without destination actions. Nothing extra is signed or sent.

Track the outcome

Track the transfer with GET /v1/transfers/{orderId} or webhooks. A transfer with destination actions completes with one of two reasons:

status.reasonMeaning
filled_destination_action_successfulThe fill happened and every step completed
filled_destination_action_failedThe fill happened, but the steps did not complete. With deliver-output-token, the bridged token went to onFailure.recipient

Both are state: "completed". With onFailure.action: "revert", a failing step stops the fill instead, and the transfer is refunded (refunded / refund_confirmed).

Plain filled means the action outcome is not confirmed yet. For a short time after the fill, a transfer with destination actions can report filled before it settles on one of the two reasons above. If you need the action outcome, keep reading the transfer, or listen for the transfer.status webhook, until the reason changes.

Steps

Steps run in order, in the same transaction as the fill. Amounts are base-unit strings.

kindWhat it doesFields
approveLets spender pull tokentoken, spender, and amount or populateDynamically: true
function-callCalls target; Across encodes the calldatatarget, functionSignature, args, optional value or populateCallValueDynamically: true
raw-callCalls target with calldata you encoded yourselftarget, calldata, optional value
native-transferSends the chain's native token to targettarget, and value or populateCallValueDynamically: true

Use the amount that arrived. You rarely know the exact output in advance, so instead of a fixed number:

  • On approve, set populateDynamically: true to approve the amount of token that arrived.
  • On a function-call argument, pass { populateDynamically: true, balanceSourceToken } to fill it with the amount of balanceSourceToken that arrived. It works on single-word types such as uint256.
  • On function-call and native-transfer, set populateCallValueDynamically: true to send all the native token that arrived.

raw-call amounts are fixed, so use function-call when you need the amount that arrived. Pass large integers as strings, and tuples or arrays as JSON arrays.

If a step fails

onFailure.action decides what happens:

onFailure.actionIf any step fails
revert (default)The fill does not happen and the transfer is refunded
deliver-output-tokenThe fill still happens and the bridged token goes to onFailure.recipient, an EVM address on the destination chain. Anything left over after successful steps goes there too

Things to know

  • App fees come off first. With appFeeBps, the steps receive the output after the app fee.
  • Gas top-up. With gasTopUp, the top-up is sent before the steps run, and onFailure.recipient must be destination.recipient.
  • Attestations. With attestation, the steps are signed too, and onFailure.recipient must be destination.recipient.
  • Refunds pay the bridged token. A refund skips the steps and pays out the token that crossed. See Refunds.
  • Bodies are strict. An unknown field in a step returns 400. The full schema is on the Quote operation.

On this page