← Back to Swap

Developer Integration

Embed the Swap to BSV widget in your application

Two Integration Options

Option 1: Redirect users to this page in a new tab
Option 2: Embed the widget in your app using an iframe with postMessage communication

Option 1: Redirect to Swap Page

Open the swap portal in a new tab with pre-filled parameters:

const swapUrl = new URL('https://swap.sendbsv.com/swap');
swapUrl.searchParams.set('bsvAddress', userWalletAddress);
swapUrl.searchParams.set('targetUsd', '10.00');
swapUrl.searchParams.set('context', 'Payment for service');
swapUrl.searchParams.set('returnUrl', window.location.href);
swapUrl.searchParams.set('state', sessionToken);

window.open(swapUrl.toString(), '_blank');

Parameters:

  • bsvAddress - Required. User's BSV receiving address
  • targetUsd - Optional. Target amount in USD
  • context - Optional. Description shown to user
  • returnUrl - Optional. Where to send user after swap
  • state - Optional. Token echoed back to your app
  • theme - Optional. "light" or "dark"

Option 2: Embed in Your App

Embed the widget using an iframe with secure postMessage communication:

// Create iframe
const iframe = document.createElement('iframe');
const embedUrl = new URL('https://swap.sendbsv.com/embed');
embedUrl.searchParams.set('bsvAddress', userWalletAddress);
embedUrl.searchParams.set('targetUsd', '10.00');
embedUrl.searchParams.set('parentOrigin', window.location.origin);
embedUrl.searchParams.set('state', sessionToken);

iframe.src = embedUrl.toString();
iframe.width = '100%';
iframe.height = '600px';
iframe.style.border = 'none';
document.getElementById('swap-container').appendChild(iframe);

// Listen for messages
window.addEventListener('message', (event) => {
  // Validate origin
  if (event.origin !== 'https://swap.sendbsv.com') return;
  if (event.data.channel !== 'SWAP_PORTAL_V1') return;
  
  switch (event.data.type) {
    case 'READY':
      console.log('Widget ready');
      break;
    case 'CLOSE_REQUESTED':
      // User clicked close
      closeModal();
      break;
    case 'CONTINUE_REQUESTED':
      // User indicated swap complete
      closeModal();
      checkWalletBalance();
      break;
  }
});

⚠️ Security Requirements

  • Always validate event.origin matches the portal domain
  • Always check event.data.channel === 'SWAP_PORTAL_V1'
  • Validate state matches your session token
  • Use HTTPS for parentOrigin in production

Message Types:

  • READY - Widget loaded and ready
  • CLOSE_REQUESTED - User clicked close/cancel
  • CONTINUE_REQUESTED - User indicated swap complete

Live Demo

See the embedded integration in action:

View Live Demo →

Important Notes

  • • This portal does not custody funds
  • • Swaps are handled entirely by SimpleSwap
  • • The portal cannot detect when a swap completes
  • • Your app should check wallet balance independently
  • • Swaps may be delayed or require verification