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.
Do NOT share your private key on this page.
Environment
Server URL: https://testnet-relayer.meson.fi
Swap Parameters
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
- JavaScript
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": ""
}'
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
- JavaScript
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": ""
}'
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)
- ethers.js v6
- ethers.js v5
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('')
}
// 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
}
// 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.
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
- JavaScript
curl -L -X POST 'https://testnet-relayer.meson.fi/api/v1/swap/{encoded}' \
-H 'Content-Type: application/json' \
--data-raw '{
"fromAddress": "",
"recipient": "",
"signature": "{signature}"
}'
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
- JavaScript
curl -L -X GET 'https://testnet-relayer.meson.fi/api/v1/swap/{swapId}'
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
.