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:Goerli TestnetSepolia TestnetBNB TestnetPolygon MumbaiArbitrum GoerliOptimistic GoerliAvalanche FujiTron Nile TestnetStarknet TestnetSKALE Europa TestnetSKALE Nebula TestnetAncient8 CelestiaTaiko KatlaX1 TestnetViction TestnetGoshen TestnetBob SepoliaTuna TestnetOneness Testnet

Token:

From Address:

To

Chain:Goerli TestnetSepolia TestnetBNB TestnetPolygon MumbaiArbitrum GoerliOptimistic GoerliAvalanche FujiTron Nile TestnetSolana TestnetStarknet TestnetAptos TestnetSui TestnetSKALE Europa TestnetSKALE Nebula TestnetAncient8 CelestiaTaiko KatlaX1 TestnetViction TestnetGoshen TestnetBob SepoliaTuna TestnetOneness 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 3 - Sign the swap data

After receiving the response from the previous API, it's necessary to sign the signingRequest to authorize the swap. 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.

Step 4 - Submit the swap

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.