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
- Describe the calls as
stepson the quote request. - Execute the quote as usual.
- 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.
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.reason | Meaning |
|---|---|
filled_destination_action_successful | The fill happened and every step completed |
filled_destination_action_failed | The 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.
kind | What it does | Fields |
|---|---|---|
approve | Lets spender pull token | token, spender, and amount or populateDynamically: true |
function-call | Calls target; Across encodes the calldata | target, functionSignature, args, optional value or populateCallValueDynamically: true |
raw-call | Calls target with calldata you encoded yourself | target, calldata, optional value |
native-transfer | Sends the chain's native token to target | target, 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, setpopulateDynamically: trueto approve the amount oftokenthat arrived. - On a
function-callargument, pass{ populateDynamically: true, balanceSourceToken }to fill it with the amount ofbalanceSourceTokenthat arrived. It works on single-word types such asuint256. - On
function-callandnative-transfer, setpopulateCallValueDynamically: trueto 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.action | If any step fails |
|---|---|
revert (default) | The fill does not happen and the transfer is refunded |
deliver-output-token | The 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, andonFailure.recipientmust bedestination.recipient. - Attestations. With
attestation, the steps are signed too, andonFailure.recipientmust bedestination.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.