API Playground

Welcome to this interactive tutorial designed to showcase the utilization of the Meson API. By following the outlined steps, you'll gain a comprehensive understanding of Meson API's operation, and even complete a cross-chain swap directly in this page.

Preparations

Before we begin, please select your preferred environment, either testnets or mainnets, and provide the required swap data. For added convenience, this playground also supports executing a cross-chain swap on mainnets, which can be beneficial for those who wish to experiment with how the Meson APIs function on mainnets.

caution

Do NOT share your private key on this page.

Environment

Server URL: https://testnet-relayer.meson.fi

Swap Parameters

From

Chain:Sepolia TestnetArbitrum SepoliaAvalanche FujiBNB TestnetOP SepoliaPolygon AmoyTron Nile TestnetStarknet SepoliaSKALE Europa TestnetSKALE Nebula TestnetAncient8 CelestiaMerlin TestnetViction TestnetTON Testnet

Token:

From Address:

To

Chain:Sepolia TestnetArbitrum SepoliaAvalanche FujiBNB TestnetOP SepoliaPolygon AmoyTron Nile TestnetSolana TestnetStarknet SepoliaAptos TestnetSui TestnetSKALE Europa TestnetSKALE Nebula TestnetAncient8 CelestiaMerlin TestnetViction TestnetTON Testnet

Token:

Recipient Address:

Amount

Amount to Swap:

Procedures to use Meson API

Ensure that you've filled out the necessary information for a cross-chain swap using the form above. Now, let's delve into the usage of the Meson API. Kindly adhere to the steps outlined below.

Step 1 - Get price

This API allows you to quickly retrieve the fee data for a cross-chain swap. While this is an optional step as the next API will also return the price data, this particular API is notably faster.

Bash

curl -L -X POST 'https://testnet-relayer.meson.fi/api/v1/price' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "from": "undefined:undefined",
    "to": "undefined:undefined",
    "amount": "",
    "fromAddress": ""
  }'

JavaScript

const res = await fetch('https://testnet-relayer.meson.fi/api/v1/price', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'undefined:undefined',
    to: 'undefined:undefined',
    amount: '',
    fromAddress: ''
  })
})
const result = await res.json()

Step 2 - Encode a swap

The Meson cross-chain swaps utilize compact encoding to condense data. This API is designed to process human-friendly parameters delivered in the request body, and in return it produces an encoded swap. The response also includes the price info and data to be signed, which must undergo a signature process prior to the submission of the swap.

Bash

curl -L -X POST 'https://testnet-relayer.meson.fi/api/v1/swap' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "from": "undefined:undefined",
    "to": "undefined:undefined",
    "amount": "",
    "fromAddress": "",
    "recipient": ""
  }'

JavaScript

const res = await fetch('https://testnet-relayer.meson.fi/api/v1/swap', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    from: 'undefined:undefined',
    to: 'undefined:undefined',
    amount: '',
    fromAddress: '',
    recipient: ''
  })
})
const result = await res.json()

Step 3a - Submit transaction to the blockchains

info

This step only supports swaps from EVM-compatible chains. If you want to initiate a swap from a non-EVM chain, please reach out to Meson team.

After receiving the response from the previous API, you should first check the fee data in the returned data to ensure there are no issues. Once confirmed, initiate the cross-chain swap by sending an on-chain transaction from fromAddress using the API returned tx object. The fields tx.to, tx.value, and tx.data are already encoded with the necessary information to interact with the Meson smart contract. Please note that if you are performing a swap with an ERC-20 token, you must first call approve on the token contract to grant sufficient allowance to tx.to (the Meson contract address) before submitting this transaction.

Step 3b - Sign the swap data & Submit the swap

info

This step only supports ERC-20 tokens. If you want to initiate a swap with native tokens (usually ETH), see Step 3a.

Another option to initiate a cross-chain swap is signing the signingRequest. This method does not require you to send an on-chain transaction, as it authorizes the Meson API to submit it on your behalf. Meson's smart contracts will inspect the signature to confirm that the submitted swap is valid. If you are a dApp developer and the swap is dispatched from a user's wallet, you can prompt the user to sign the data in their browser. However, if the swap is initiated from your personal wallet, you have the option to sign it on your server. Here are some sample codes for reference.

In Browser (Metamask)

async function signDataWithMetamask (signingRequest) {
  const ethereum = window.ethereum
  const accounts = await ethereum.request({ method: 'eth_requestAccounts' })

  const hexEthHeader = utf8ToHex('\x19Ethereum Signed Message:\n52')

  const msg = signingRequest.message.replace(hexEthHeader, '')
  const signature = await ethereum.request({ method: 'personal_sign', params: [msg, accounts[0]] })

  return signature
}

function utf8ToHex(utf8Str) {
  return Array.from(utf8Str)
    .map(char => char.charCodeAt(0).toString(16).padStart(2, '0'))
    .join('')
}

ethers.js v6

// For ethers@^6
const { Wallet, keccak256 } = require('ethers')

// The private key for fromAddress
const wallet = new Wallet(process.env.PRIVATE_KEY)

function signDataV6 (signingRequest) {
  if (keccak256(signingRequest.message) !== signingRequest.hash) {
    throw new Error('Invalid hash')
  }

  const sig = wallet.signingKey.sign(signingRequest.hash)
  return sig
}

ethers.js v5

// For ethers@^5
const { Wallet, utils } = require('ethers')

// The private key for fromAddress
const wallet = new Wallet(process.env.PRIVATE_KEY)

function signDataV5 (signingRequest) {
  if (utils.keccak256(signingRequest.message) !== signingRequest.hash) {
    throw new Error('Invalid hash')
  }

  const sig = wallet._signingKey().signDigest(signingRequest.hash)
  return utils.joinSignature(sig)
}

ℹ️ Please complete step 2 to obtain the swap data that needs signing.

Upon completing the previous step and acquiring the encoded data along with its corresponding signature, this API will initiate the cross-chain swap process via the Meson relayer. The relayer then distributes the data and executes the transaction across the respective blockchains. Provided the signature is authenticated, the API will generate and return a unique swap ID. This ID can then be utilized to monitor the status of the swap.

note

You can re-call this API with the same encoded data and fromAddress. Meson's smart contract prevents double spending by ensuring only ONE execution per encoded. The response will always be the same swap ID.

Bash

curl -L -X POST 'https://testnet-relayer.meson.fi/api/v1/swap/{encoded}' \
  -H 'Content-Type: application/json' \
  --data-raw '{
    "fromAddress": "",
    "recipient": "",
    "signature": "{signature}"
  }'

JavaScript

const res = await fetch('https://testnet-relayer.meson.fi/api/v1/swap/{encoded}', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    fromAddress: '',
    recipient: '',
    signature: "{signature}"
  })
})
const result = await res.json()

ℹ️ Please complete steps 2 & 3.

Step 5 - Check status

To check the status of a submitted swap, use the swap ID from the previous API. You can manually use the Meson testnet explorer or employ this API for automatic status updates on your server.

Bash

curl -L -X GET 'https://testnet-relayer.meson.fi/api/v1/swap/{swapId}'

JavaScript

const res = await fetch('https://testnet-relayer.meson.fi/api/v1/swap/{swapId}')
const result = await res.json()

ℹ️ Please complete step 4 to obtain the swapId.