# Quickstart Guide

### **Introduction** <a href="#introduction" id="introduction"></a>

MAYAChain allows native L1 Swaps. On-chain [Memos](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/transaction-memos) are used instruct MAYAChain how to swap, with the option to add [price limits](#price-limits) and [affiliate fees](#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.

{% hint style="info" %}
The following examples use a free, hosted API provided by the Maya Protocol team. If you want to run your own full node, please see [Connecting to MAYAChain.](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/connecting-to-mayachain)
{% endhint %}

### 1. Determine the correct asset name. <a href="#id-1.-determine-the-correct-asset-name" id="id-1.-determine-the-correct-asset-name"></a>

MAYAChain uses a specific [asset notation.](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/asset-notation) Available assets are at: [​Pools Endpoint](https://mayanode.mayachain.info/mayachain/pools).

BTC => `BTC.BTC`

ETH => `ETH.ETH`

{% hint style="info" %}
Only available pools can be used. (`where 'status' == Available)`
{% endhint %}

### 2. Query for a swap quote. <a href="#id-2.-query-for-a-swap-quote" id="id-2.-query-for-a-swap-quote"></a>

{% hint style="info" %}
All amounts are 1e8. Multiply native asset amounts by 100000000 when dealing with amounts in THORChain. 1 BTC = 100,000,000.
{% endhint %}

**Request**: *Swap 1 BTC to ETH and send the ETH to* `0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430`.

<https://mayanode.mayachain.info/mayachain/quote/swap?from_asset=BTC.BTC&to_asset=ETH.ETH&amount=100000000&destination=0x86d526d6624AbC0178cF7296cD538Ecc080A95F1>

​​**Response**:

```bison
{
  "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 u&#x70;*. You will pay an outbound gas fee of 0.0085 ETH and will incur 168 basis points (1.68%) of slippage.*

{% hint style="info" %}
Full quote swap endpoint specification can be found here: ​<https://mayanode.mayachain.info/mayachain/doc>.

See an example implementation LINK HERE
{% endhint %}

​If you'd prefer to calculate the swap yourself, see the [Fees](https://docs.mayaprotocol.com/deep-dive/how-it-works/fees) section to understand what fees need to be accounted for in the output amount. Also, review the [Transaction Memos](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/transaction-memos) section to understand how to create the swap memos.

### 3. Sign and send transactions on the from\_asset chain. <a href="#id-3.-sign-and-send-transactions-on-the-from_asset-chain" id="id-3.-sign-and-send-transactions-on-the-from_asset-chain"></a>

Construct, sign and broadcast a transaction on the BTC network with the following parameters:

Amount => `1.0`

Recipient => `bc1qlccxv985m20qvd8g5yp6g9lc0wlc70v6zlalz8`

Memo => `=:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430`

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
Learn more about how to construct inbound transactions for each chain type here: ​[Sending Transactions](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/sending-transactions)
{% endhint %}

### 4. Receive tokens. <a href="#id-4.-receive-tokens" id="id-4.-receive-tokens"></a>

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 <a href="#additional-considerations" id="additional-considerations"></a>

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="success" %}
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.
{% endhint %}

#### Price Limits <a href="#price-limits" id="price-limits"></a>

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:**

<https://mayanode.mayachain.info/mayachain/quote/swap?amount=100000000&from_asset=BTC.BTC&to_asset=ETH.ETH&destination=0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430&liquidity_tolerance_bps=500>

The resulting memo will include a minimum output amount appended to the end:

```
=:ETH.ETH:0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430:1762972381
```

This 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_OUTPUT
```

For streaming swaps with price limits:

```
=:TO_ASSET:DESTINATION:MINIMUM_OUTPUT/STREAMING_INTERVAL/STREAMING_QUANTITY
```

**Error Handling**

Common errors you might encounter:

* **Price Limit Exceeded**: `"emit asset 2651686248 less than price limit 2719908600"` - The output fell below your tolerance threshold
* **Invalid Range**: `"liquidity tolerance basis points must be less than 10000"` - Tolerance value exceeds maximum
* **Conflicting Parameters**: `"must only include one of: tolerance_bps or liquidity_tolerance_bps"` - Both parameters specified

**Best Practices**

1. Always use `liquidity_tolerance_bps` instead of `tolerance_bps` for accurate protection
2. Request fresh quotes immediately before transaction submission
3. Set reasonable tolerance based on pool depth and market conditions (typical range: 100-500 bps)
4. Consider using [Streaming Swaps](https://docs.mayaprotocol.com/mayachain-dev-docs/introduction/swapping-guide/streaming-swaps) for larger trades to reduce slippage
5. Monitor both `expected_amount_out` and `inbound_address` between quotes

### Affiliate Fees <a href="#affiliate-fees" id="affiliate-fees"></a>

Specify affiliate\_*address* and *affiliate\_bps t*o skim a percentage of the *expected*\_*amount\_out.*&#x200B;​

<https://mayanode.mayachain.info/mayachain/quote/swap?amount=100000000&from_asset=BTC.BTC&to_asset=ETH.ETH&destination=0x3021c479f7f8c9f1d5c7d8523ba5e22c0bcb5430&affiliate=wr&affiliate_bps=10>

```json
{
  "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](https://docs.mayaprotocol.com/mayachain-dev-docs/concepts/fees "mention")

### Streaming Swaps <a href="#streaming-swaps" id="streaming-swaps"></a>

[Streaming Swaps](https://docs.mayaprotocol.com/mayachain-dev-docs/introduction/swapping-guide/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 <a href="#error-handling" id="error-handling"></a>

TBA

#### Support <a href="#support" id="support"></a>

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.