Skip to main content

​
Overview

Custom payloads let you attach a small piece of data to a cross-chain swap or bridge. This data travels with the transfer and can be read by your destination contract or backend once the funds arrive. The Swap SDK sends this payload as raw bytes. It does not interpret or modify the contents, and your destination logic is responsible for decoding them. Some routes, such as HyperCore deposits, construct their own fixed payload instead. This page explains what custom payloads are, why they are useful, and how to include them when calling the Swap SDK.

​
Definition and Guarantees

A custom payload is an arbitrary sequence of bytes attached to a supported swap route. When a route accepts payloads, the SDK forwards the raw bytes exactly as provided.

​
Core guarantees

  • Payloads are forwarded verbatim; the SDK does not transform, validate, or decode them. Some routes hash the payload into an order key for verification or indexing, but the raw bytes sent cross-chain are unchanged.
  • When a route supports payloads (e.g., MCTP, Fast MCTP, Swift), it sets the payloadType enum accordingly.
  • The raw payload bytes are included in the cross-chain message or transaction and reach the destination exactly as provided. Your destination logic is responsible for parsing them.
  • Some routes do not accept caller-supplied payloads, may ignore them, or construct their own fixed payload (such as HyperCore or specific lock-fee/auction paths).

​
Why use a custom payload?

Custom payloads let you attach additional context to a transfer, such as user metadata, routing parameters, or application-specific instructions for your destination logic. If your integration does not require extra data on the destination chain, you can omit it. Only specific swap routes support caller-supplied payloads; others will reject or override the bytes.

​
Use Custom Payloads in the Swap SDK

You can attach a custom payload from EVM, Solana, or Sui by passing a Buffer or Uint8Array to the relevant SDK call. Payload support depends on the chain and the route type, so refer to the sections below for precise behavior. Payloads should stay small. Each chain and route has its own message-size limits, and larger payloads may increase fees or cause the swap to fail if the underlying protocol rejects the message.

​
Fetching quote

To ensure you receive a quote that supports custom payloads, you must pass payload: 'true' in the quoteOptions parameter when using fetchQuote or generateFetchQuoteUrl.
Important
  • Custom payloads are not supported by all route types provided by Mayan. Therefore, it is important to explicitly indicate that you intend to use custom payloads so the quote service can return only routes that support them.

​
EVM

On EVM, a custom payload can be included in calls such as swapFromEvm, or getSwapFromEvmTxPayload. Example: 
import { swapFromEvm } from '@mayanfinance/swap-sdk';

const customPayload = Buffer.from('hello-world');

const tx = await swapFromEvm(
  quote,
  fromAddress,
  destAddr,
  null,          // optional referrer
  signer,
  undefined,     // optional permit
  undefined,     // optional overrides (gas settings)
  customPayload
);

​
Solana

On Solana, a custom payload is supported on specific routes, including MCTP, Fast MCTP, and Swift v2, under route-specific conditions. Example: 
import { swapFromSolana } from '@mayanfinance/swap-sdk';

const customPayload = Buffer.from('hello-world');

const result = await swapFromSolana(
  quote,
  swapperWalletAddress,
  destinationAddress,
  referrerAddresses,
  signTransaction,
  connection,
  undefined,         // extraRpcs
  undefined,         // sendOptions
  undefined,         // jitoOptions
  { customPayload }  // forwarded only for supported routes
);

​
Sui

On Sui, a custom payload is passed directly as the payload argument to createSwapFromSuiMoveCalls. Example: 
import { createSwapFromSuiMoveCalls } from '@mayanfinance/swap-sdk';

const customPayload = Buffer.from('hello-world');

const tx = await createSwapFromSuiMoveCalls(
  quote,
  swapperWalletAddress,
  destinationAddress,
  referrerAddresses,
  customPayload,
  suiClient
);

​
Summary

Custom payloads let you attach application-specific data to supported Mayan swap routes. Only specific paths accept payloads, and each chain has its own conditions. Always confirm the quote type and route before attaching a payload, and ensure your destination logic is prepared to decode the data you send.