Important Integration Notes

Handling of failed bridging operations

Automatic refunds

Due to the non-atomic nature of cross chain operations, it is possible that in case of a failure, the user will be refunded in a token that is different than the one they started with. For Across, Mayan Swift, Relay, Squid Coral, the user will be refunded in the bridging token (different that original sell token for routes that have a swap or wrap step) on origin chain.

Retry of the transaction on destination chain

In case of Stargate V2, it is possible that the funds will be delivered to destination chain, but won't be delivered to a selected address on destination chain. It can happen in rare cases where the destination chain transaction fails. Status API will return a transaction that can be submitted to re-trigger delivery of the funds to the wallet on the destination chain.

Monetisation

Integrators have the ability to add integrator fees. At the moment, it's possible to collect fees in sell token on origin chain on EVM chains. It is currently not possible to collect fees on routes that have Solana as origin chain. It is also possible to collect multiple fees, sent to different recipients as a part of a single trade.

The fees will be automatically collected and sent to the provided wallet as a part of origin chain transaction.

Example parameters to fetch a quote with monetisation enabled

const quoteParams = new URLSearchParams({
    originChain: '8453',
    destinationChain: '42161',
    sellToken: '0x4200000000000000000000000000000000000006',
    buyToken: '0xaf88d065e77c8cc2239327c5edb3a432268e5831',
    sellAmount: '100000000000000000000',
    originAddress: '$USER_TAKER_ADDRESS', 
    sortRoutesBy: 'price',
    
    // Monetisation parameters
    feeRecipient: '0x2fb3a9fb601808e110b1ade14068d69c3bfe0fef' // address to which the fee should be sent
    feeBps: 100 // The amount in bps of the amount that will be delivered to the feeRecipient
    
    // Or, to collect multiple fees
    feeRecipient: '0x2fb3a9fb601808e110b1ade14068d69c3bfe0fef,0x3bb2a1fb601808e110b1ade14068d69c3bfe0fef' // addresses to which the fee should be sent
    feeBps: '100,200' // The amounts in bps of the amount that will be delivered to the `feeRecipient`s
    
    // In both cases feeToken is optional as currently it is only possible to collect fees in sellToken
});