Mayan integration with the API, SDK, and swap widget

Mayan offers a swap SDK for custom interfaces, direct API access for integrations building their own transactions, and a configurable widget for embedded swaps. The SDK wraps quoting and prepares transactions for supported source chains, reducing chain-specific construction work. Direct API access suits unsupported programming languages or a backend that only needs quotes. The widget supplies the swap interface and exposes settings for supported chains, token lists, appearance, and referral fees. Choosing among them changes which parts of transaction construction and presentation the application owns. It doesn't turn a quote, signature, or submitted transaction into evidence of destination delivery.

Integration options and their execution boundaries

The widget supplies a ready-made interface; the SDK supports a custom one while constructing swap transactions. Direct API access leaves transaction construction with the application. Source-chain differences also matter inside the SDK, especially when a helper returns an unsigned transaction.

These options share the underlying protocol. The integration surface alone doesn't establish which route a token pair receives; the quote supplies that distinction.

When does the SDK fit a custom swap interface?

The SDK lets an application keep its own screens while using chain-specific transaction builders wrapped around the Quote API. The package is @mayanfinance/swap-sdk , and fetchQuote retrieves the available routes for a pair.

EVM and Solana integrations use swapFromEvm and swapFromSolana , respectively. The Sui helper createSwapFromSuiMoveCalls returns a transaction the application must sign and broadcast. For Sui, SDK v15 requires @mysten/sui v2 with a Core API client. Sui-to-HyperCore transfers are temporarily disabled; the helper rejects that destination.

The EVM helper getSwapFromEvmTxPayload returns a payload without sending it. On Solana, createSwapFromSolanaInstructions returns instructions the app can compose into its own transaction. These paths retain SDK construction support while leaving the final send with the application.

For CommonJS require() , documented minimums are Node 20.19 within the 20.x release line and 22.12 within 22.x. Incompatible older runtimes fail with ERR_REQUIRE_ESM because the package loads ESM-only dependencies at import. ESM imports work on modern runtimes.

Direct API access transfers transaction work to the app

Direct API access suits a backend that only fetches quotes or an execution stack outside the SDK's supported language. When that integration also executes swaps, it must construct transactions and arrange signing for each source chain.

The selected quote's type determines the execution contract and required route-specific fields. Values include SWIFT , MCTP , FAST_MCTP , and WH . An array can contain different route types, so branching must use the actual selected object.

ERC-20 inputs on EVM require spending authorization for the Forwarder before the swap. An allowance must cover at least effectiveAmountIn64 ; a token supporting EIP-2612 can use a permit signature instead. Native-token inputs don't need this approval.

Direct integrations also encode referrer addresses and verify they match the quote. Solana instructions and Sui Move calls remain chain-specific construction work. A successful quote response supplies execution data; it doesn't replace these responsibilities.

Output fields, fees, and the displayed amount

A quote separates an expected output from a minimum output and the minimum remaining after relayer fees. Those fields answer different interface questions, so a single unlabeled number can obscure what the user would receive.

expectedAmountOut represents the quoted expectation, while minAmountOut is the output floor. The minReceived field gives the minimum output after relayer fees have been deducted. The quote also carries protocolBps and referrerBps , which identify fees applied to that particular option.

View full-size image

For a Swift quote with swiftAuctionMode set to 3 , expectedAmountOut is the exact settlement amount.

etaSeconds expresses estimated settlement time in seconds, while clientEta supplies a display string. Neither proves the order has completed.

What can the swap widget configuration change?

The widget builder configures supported chains, token lists, colors, and overall appearance, alongside referrer fees and receiving addresses. Selecting a chain or token for display doesn't establish liquidity for a proposed swap. The widget remains an integration surface, with execution depending on the supported options available for the requested pair.

View full-size image

Route availability and gas belong to the selected quote

Route controls determine which families the quote request allows, while returned options establish which routes are available for the pair. The flags swift , mctp , fastMctp , and wormhole enable or disable those families. Omitting them allows all; it doesn't guarantee an option from each one.

The selected quote's gasless field, when true, means a relayer submits the transaction and pays its gas after the user signs a message. An interface can't infer that property from general support for gas abstraction. Zaps extend a swap with destination actions, including deposits and staking; selecting an integration surface alone doesn't specify that action. Custom flows therefore need to distinguish the requested asset movement from any destination operation attached to it.

Completion tracking and refundable orders

The Explorer API reports whether an order is in progress, completed, or refunded, allowing a custom interface to distinguish submission from destination delivery. Its clientStatus field exposes INPROGRESS , COMPLETED , and REFUNDED . The first remains open; the other two are terminal states with different outcomes.

COMPLETED means destination delivery, and toAmount identifies what actually arrived. A gasless swapFromEvm call returns an order hash, which the same tracking interface accepts. The returned identifier locates the order; its status establishes the outcome.

deadline64 marks the point after which an order cannot be filled and becomes refundable. Refund eligibility doesn't confirm a completed refund. On Swift, a source-chain conversion can mean a refund returns the locked asset, typically USDC or ETH, instead of the original input token. Show the refunded asset and amount, along with the refund relayer fee returned in the quote.

View full-size image

Still have questions?