Skip to main content

Send a Cross-Chain Swap from Native BTC

info

This is a beta feature of Meson. If you wish to use it, please reach out to Meson team for further assistance.

Meson allows you to initiate a cross-chain swap directly from native Bitcoin (BTC) to assets on supported chains. This guide walks you through encoding your swap request and sending BTC to Meson to complete the transaction.

1. Encode the Swap​

Start by using the Encode Swap API to create an encoded. This encoded payload uniquely identifies your swap and must be included when checking its status.

Below is an example request body for swapping 0.001 native BTC (Bitcoin mainnet) to BTCB on BNB Smart Chain:

{
  "from": "bitcoin:btc",
  "to": "bnb:btc",
  "amount": "0.001",
  "fromAddress": "bc1qrm4en4jl2lht3rd8drjr8vng2xv36fw54fukyh",
  "recipient": "0x666d6b8a44d226150ca9058beebafe0e3ac065a2"
}

A typical response from the API will look like this:

{
  "encoded": "0x0100000003e8d8000000000013cd8212000000001e0069318c0602caf20000f3",
  "fromAddress": "bc1qrm4en4jl2lht3rd8drjr8vng2xv36fw54fukyh",
  "recipient": "0x666d6b8a44d226150ca9058beebafe0e3ac065a2",
  "initiator": "0x6546580848f4ed7ed386771143aff78dc972f8f6",
  "fee": {
    "serviceFee": "0",
    "lpFee": "0.00003",
    "totalFee": "0.00003"
  }
}

2. Send BTC to Meson​

After generating the encoded, send the exact BTC amount specified in your request to the official Meson Bitcoin deposit address listed at: ➡️ /getting-started/supported#bitcoin

Once the transaction is broadcast, obtain the Bitcoin transaction hash (txid) from your wallet or node. You will use this hash to notify Meson in the next step.

3. Notify Meson of Your Bitcoin Transaction​

After your BTC transaction is broadcast (no need to wait for confirmations), notify Meson by sending a PUT request to the relayer endpoint:

await fetch(`https://relayer.meson.fi/api/v1/swap/${encoded}`, {
  method: 'PUT',
  body: JSON.stringify({
    tx: `bitcoin:${hash}`,
    event: 'EXECUTED'
  })
})
  • encoded — Your encoded swap string
  • hash — The Bitcoin transaction hash (txid)
  • event: 'EXECUTED' — Indicates that the BTC transfer has been executed

After receiving this notification, Meson will begin monitoring the Bitcoin transaction on-chain.

4. Blockchain Confirmations & Swap Completion​

Once notified, Meson will automatically track your BTC transaction on the Bitcoin network.

  1. Meson waits for sufficient Bitcoin confirmations
    • Typically requires 30–60 minutes depending on network congestion
  2. Meson executes the cross-chain transaction on the destination chain
    • Usually completed within ~5 minutes after confirmations
  3. Your swap is finalized and the destination asset is delivered to your recipient address.

You can track the full lifecycle of your swap using Meson Explorer:

https://explorer.meson.fi/swap/{encoded}

Replace {encoded} with your actual encoded swap value to see real-time status updates.