Getting started
Do I need an API key?
No. The SDK and the Quote API work without one. AnapiKey on the quote request raises the per-IP rate limit, which matters at production volume. See SDK.
How do I get an API key?
Email support@mayan.finance or reach the team in Discord.Which tokens and chains are supported?
Any token with a contract address, across every chain Mayan supports. There is no whitelist and no listing process, so adding an asset is never an integration change. See chains & contracts.Do I choose the route?
fetchQuote returns the routes available for a pair, each tagged with its transfer method as type. You choose which one to execute. By default you get at most two: the quickest first, then the best return.
What is the difference between Swift, MCTP and Wormhole Swap?
Swift is the fastest path and covers most swaps, settling in as little as 2 seconds. MCTP routes over Circle’s CCTP and suits high-value stablecoin transfers, settling in as little as 5 seconds. Wormhole Swap uses the Wormhole Token Bridge for low-slippage transfers of assets like SOL and ETH, and settles in under a minute. See Swift, MCTP and Wormhole Swap.How large a swap can Mayan handle?
It depends on the route. Swift carries single transfers up to around $1M, depending on the chain. MCTP and Fast MCTP carry up to around $10M.Amounts and pricing
What happens if the price moves while the swap is in flight?
minAmountOut is part of what the user signs, so the order cannot fill below it. If no driver will fill it at or above that floor before the deadline, the order is refunded rather than filled at a worse rate.
Can I guarantee the exact output amount?
On same-asset transfers of USDC, USDT and ETH, yes. Those quotes come back withswiftAuctionMode: 3 and settle exact-out, so the recipient receives exactly expectedAmountOut. See Guaranteed Price.
How do I earn on swaps I route?
Set areferrer address and referrerBps on the quote, then pass the matching referrerAddresses at swap time. The fee is collected onchain automatically. See fees & earning.
Execution
Do I need to approve a token before swapping?
On EVM, yes, for ERC20 inputs. Approve the Mayan Forwarder contract, available asaddresses.MAYAN_FORWARDER_CONTRACT. If the token supports EIP-2612 you can pass a permit instead. See executing swaps.
Does the user need gas on the destination chain?
Not if you request it.gasDrop delivers native gas alongside the output, so a user arriving on a chain they have not used can transact immediately. See gas on destination.
Can a user swap without holding native gas on the source chain?
On supported routes, yes. The user signs a message rather than a transaction and a relayer submits it. Request it withgasless: true. See gasless execution.
Why did swapFromEvm return a string instead of a transaction?
The quote was gasless. On a gasless quote swapFromEvm returns an order hash, which you pass to the Explorer API exactly as you would a transaction hash.
Can I run an action on the destination chain when the funds land?
Yes. Attach a payload to the swap and your destination logic acts on it as the funds arrive. Pass{ payload: "true" } as the second argument of fetchQuote so only payload-capable routes are returned. See Zaps.
After the swap
How do I know when a swap is done?
Poll the Explorer API with the source transaction hash and readclientStatus. INPROGRESS is the only non-terminal state; COMPLETED and REFUNDED are final. See track transactions.
Why did my user get back a different token than they sent?
The order was refunded. On Swift, the input may be converted into the primary locked asset on the source chain, typically USDC or ETH, before the order opens. A refund returns the converted asset. Surface this in your interface. See refunds.Can a refund go to a different address than the one that signed?
On Swift quotes only, usingswiftRefundAddress. Request the quote with gasless: false, since gasless Swift orders require the refund address to match the signer. See executing swaps.
Does Mayan ever hold user funds?
No. The contracts are trustless and permissionless, and no party can freeze or move user assets. See security & audits.Troubleshooting
require() throws ERR_REQUIRE_ESM
The SDK loads ESM-only dependencies at import time. Use Node 20.19 or later, or 22.12 or later, if you consume the package with require(). Importing as ESM works on any modern runtime.
Sui throws core.listCoins is not a function
SDK v15 requires @mysten/sui v2 and a Core API client. A v1 SuiClient fails. SuiGrpcClient is recommended.
The SDK fails to bundle in React Native
Metro and some other bundlers cannotrequire() an ES module. Import the SDK as ESM. A scaffold project is available.