Quickstart Guide
Make a cross-chain swap on MAYAChain in less than 5 minutes.
Introduction
MAYAChain allows native L1 Swaps. On-chain Memos are used instruct MAYAChain how to swap, with the option to add price limits and affiliate fees. MAYAChain nodes observe the inbound transactions and when the majority have observed the transactions, the transaction is processed by threshold-signature transactions from MAYAChain vaults.
Let's demonstrate decentralized, non-custodial cross-chain swaps. In this example, we will build a transaction that instructs MAYAChain to swap native Bitcoin to native Ethereum in one transaction.
1. Determine the correct asset name.
MAYAChain uses a specific asset notation. Available assets are at: Pools Endpoint.
BTC => BTC.BTC
ETH => ETH.ETH
2. Query for a swap quote.
Request: Swap 1 BTC to ETH and send the ETH to 0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430.
Response:
{
"expected_amount_out": "1855545107",
"fees": {
"affiliate": "0",
"asset": "ETH.ETH",
"outbound": "840000"
},
"inbound_address": "bc1qqtemwlu9ju3ts3da5l82qejnzdl3xfs3lcl4wg",
"inbound_confirmation_blocks": 1,
"inbound_confirmation_seconds": 600,
"memo": "=:ETH.ETH:0x86d526d6624AbC0178cF7296cD538Ecc080A95F1",
"outbound_delay_blocks": 179,
"outbound_delay_seconds": 2685,
"slippage_bps": 168
}If you send 1 BTC to bc1qlccxv985m20qvd8g5yp6g9lc0wlc70v6zlalz8 with the memo =:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430, you can expect to receive 18.55545107 ETH.
For security reasons, your inbound transaction will be delayed by 600 seconds (1 BTC Block) and 2685 seconds (or 179 native MAYAChain blocks) for the outbound transaction, 3285 seconds all up. You will pay an outbound gas fee of 0.0085 ETH and will incur 168 basis points (1.68%) of slippage.
If you'd prefer to calculate the swap yourself, see the Fees section to understand what fees need to be accounted for in the output amount. Also, review the Transaction Memos section to understand how to create the swap memos.
3. Sign and send transactions on the from_asset chain.
Construct, sign and broadcast a transaction on the BTC network with the following parameters:
Amount => 1.0
Recipient => bc1qlccxv985m20qvd8g5yp6g9lc0wlc70v6zlalz8
Memo => =:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430
Never cache inbound addresses! Quotes should only be considered valid for 10 minutes. Sending funds to an old inbound address will result in loss of funds.
4. Receive tokens.
Once a majority of nodes have observed your inbound BTC transaction, they will sign the Ethereum funds out of the network and send them to the address specified in your transaction. You have just completed a non-custodial, cross-chain swap by simply sending a native L1 transaction.
Additional Considerations
There is a rate limit of 1 request per second per IP address on /quote endpoints. It is advised to put a timeout on frontend components input fields, so that a request for quote only fires at most once per second. If not implemented correctly, you will receive 503 errors.
For best results, request a new quote right before the user submits a transaction. This will tell you whether the expected_amount_out has changed or if the inbound_address has changed. Ensuring that the expected_amount_out is still valid will lead to better user experience and less frequent failed transactions.
Price Limits
MAYAChain offers multiple mechanisms to protect users from excessive slippage during swaps. Without price limits, users could experience unbounded slippage and receive significantly less than expected.
Recommended: liquidity_tolerance_bps
This is the recommended parameter for controlling maximum acceptable slippage. It calculates the minimum output amount after accounting for outbound fees, providing accurate protection.
Key characteristics:
Measured in basis points (bps): 100 bps = 1%, 500 bps = 5%
Range: 0-9,999 basis points
Calculated relative to the
expected_amount_out(after fees)If slippage exceeds this threshold, the transaction reverts
Example Request:
The resulting memo will include a minimum output amount appended to the end:
=:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430:1762972381This tells MAYAChain to revert the transaction if the final output amount is less than the calculated limit (expected_amount_out minus 5% tolerance).
Alternative: tolerance_bps (Not Recommended)
This older parameter exists but has a significant limitation: it calculates the price limit based on a feeless swap price and does not account for outbound fees. This often results in failed transactions when the actual output (after fees) falls below the limit.
Why it's not recommended:
Does not consider outbound gas fees in the calculation
Can cause legitimate swaps to fail unexpectedly
Less accurate protection for users
Important Notes:
You can only use one tolerance parameter per swap (not both)
Using both will result in an error:
"must only include one of: tolerance_bps or liquidity_tolerance_bps"Tolerance values must be less than 10,000 basis points (100%)
Memo Format with Price Limits
When price limits are applied, the memo structure includes the minimum output amount:
=:TO_ASSET:DESTINATION:MINIMUM_OUTPUTFor streaming swaps with price limits:
=:TO_ASSET:DESTINATION:MINIMUM_OUTPUT/STREAMING_INTERVAL/STREAMING_QUANTITYError Handling
Common errors you might encounter:
Price Limit Exceeded:
"emit asset 2651686248 less than price limit 2719908600"- The output fell below your tolerance thresholdInvalid Range:
"liquidity tolerance basis points must be less than 10000"- Tolerance value exceeds maximumConflicting Parameters:
"must only include one of: tolerance_bps or liquidity_tolerance_bps"- Both parameters specified
Best Practices
Always use
liquidity_tolerance_bpsinstead oftolerance_bpsfor accurate protectionRequest fresh quotes immediately before transaction submission
Set reasonable tolerance based on pool depth and market conditions (typical range: 100-500 bps)
Consider using Streaming Swaps for larger trades to reduce slippage
Monitor both
expected_amount_outandinbound_addressbetween quotes
Affiliate Fees
Specify affiliate_address and affiliate_bps to skim a percentage of the expected_amount_out.
{
"expected_amount_out": "1851200268",
"fees": {
"affiliate": "1854014",
"asset": "ETH.ETH",
"outbound": "960000"
},
"inbound_address": "bc1qqtemwlu9ju3ts3da5l82qejnzdl3xfs3lcl4wg",
"inbound_confirmation_blocks": 1,
"inbound_confirmation_seconds": 600,
"memo": "=:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430::wr:10",
"outbound_delay_blocks": 178,
"outbound_delay_seconds": 2670,
"slippage_bps": 168
}Notice how wr:10 has been appended to the end of the memo. This instructs MAYAChain to skim 10 basis points from the swap. The user should still expect to receive the expected_amount_out, meaning the affiliate fee has already been subtracted from this number.
For more information on affiliate fees: Fees
Streaming Swaps
Streaming Swaps can be used to break up trades to reduce slip fees. Streaming swaps are currently enabled with a minimum basis point fee of 5 (0.05%).
Specify streaming_interval and streaming_quantity in your swap memo to use streaming swaps. For example:
/10/0- Let the protocol determine optimal quantity, swap every 10 blocks/5/3- Execute 3 sub-swaps, one every 5 blocks
The protocol will automatically calculate the optimal swap quantity if you set it to 0. This feature helps large trades achieve better price execution by allowing arbitrageurs to rebalance pools between sub-swaps.
Error Handling
TBA
Support
Developers experiencing issues with these APIs can go to the Maya Protocol Discord server (LINK) for assistance. Interface developers should subscribe to the #interface-alerts channel for information pertinent to the endpoints and functionality discussed here.
Last updated
Was this helpful?