Multi-hop transfers

Constructing the Multi-Hop Transfer Payload

This is an advanced feature and it's recommended to use the quote endpoint of the API to create multi-hop transfers.

To initiate a multi-hop transfer, you must pack a set of parameters into a single bytes payload using Solidity ABI encoding. This payload communicates the final routing and fallback details for the transaction. The encoded array is then passed as data in the transferTo , transferToWPermit functions of a Lucid Wrapper contract, or as emittedMessage in Wrappers of external bridges (like the Across Wrapper)

const abiCoder = ethers.AbiCoder.defaultAbiCoder()
return abiCoder.encode(
  ['bytes32', 'uint32', 'address', 'address', 'address'],
  [
    multistepTransactionReference,
    finalDestinationChainId,
    finalDestinationTokenAddress,
    finalDestinationRecipientAddress,
    refundAddress,
  ],
)

Parameter Breakdown

Order	Type	Name	Description
1	bytes32	multistepTransactionReference	A random identifier used to correlate this transfer across multiple chains or hops.
2	uint32	finalDestinationChainId	The chain ID where the user ultimately wants funds delivered.
3	address	finalDestinationTokenAddress	The token contract address on the final destination chain.
4	address	finalDestinationRecipientAddress	The address that should receive the tokens once the final hop is executed.
5	address	refundAddress	A fallback address where funds should be returned if the transfer cannot be completed.

Encoding Format

The ABI encoding uses the following type layout:

['bytes32', 'uint32', 'address', 'address', 'address']

And you must pass the values in exactly the same order. The output of abiCoder.encode(...) is a 0x-prefixed hex string suitable to be sent as call data in the transaction initiating the multi-hop process.

---

Notes for Integrators

• Make sure multistepTransactionReference is already a unique and random bytes32 value

• finalDestinationChainId should match the canonical EVM chain ID of the target network.

• If no refund logic is needed, you may still be required to pass a non-zero address, but it is highly recommended to set a refund address you control that would receive the tokens on the mid-point chain if the transfer to the final destination chain cannot be sent.

Transfers using external bridges

For multi-hop transfers initiated from a Lucid Wrapper contract, please refer to this page.

For assets that are not natively supported by an Asset Controller (for example, native USDC on Base), you can still perform a multi-hop transfer by initiating it through a supported external bridge Wrapper. The construction of the multi-hop payload remains the same, you simply send it to the Wrapper contract of the external bridge (currently Across and Relay, with additional bridge integrations coming soon).

Across Wrapper

The deployed contract addresses are available in this page.

To initiate a transfer through Across, call the deposit() function on the Across Wrapper contract. The multi-hop configuration should be provided via the emittedMessage field within the DepositInput struct. Before submitting the transaction, it is strongly recommended to use the Quote API to retrieve the correct configuration and supported parameters for the transfer.

Across Wrapper ABI:

16KB

acrossWrapper.abi.json

Open

Relay Wrapper

The deployed contract addresses are available in this page.

To initiate a transfer through Relay, call the depositNative() function for Ether transfers or the depositErc20() function for ERC20 transfers on the Relay Wrapper contract. The multi-hop configuration should be provided as the emittedMessage input parameter.

Before submitting the transaction, it is strongly recommended to use the Quote API to retrieve the correct configuration and supported parameters for the transfer. Otherwise, you'll have to use Relay's API to get an orderId generated, which is then passed to the Wrapper contract.

Relay Wrapper ABI:

10KB

relayWrapper.abi.json

Open

Please reach out if you are looking to integrate with Multi-hop.