Embed a crypto swap widget with an iframe or SDK: setup steps, security checks, compliance questions and how to choose a widget that fits your site.
To embed a crypto swap widget, you paste an iframe (or load a small JavaScript snippet) into the page where you want the swap form to appear. The provider’s hosted interface then handles quotes, wallet connection and execution. The embed itself takes minutes. The decisions around it take longer: who holds the funds, how the iframe talks to your page, what you must disclose, and how the widget fits your design and your business model.
This guide walks through all of it, from the first line of HTML to the security headers you should set before going live.
frame-ancestors policy on your own pages.A crypto swap widget is an embeddable user interface that lets visitors exchange one cryptocurrency for another without leaving your site. According to the SwapKit documentation, such a widget is a drop-in, non-custodial swap interface that deals with wallets, quoting, approvals and execution, so the host site does not have to. Integration is typically a plain <iframe src="..."> tag or a JavaScript SDK that renders the component dynamically.
That description covers a wide family of products. They differ in ways that matter to you:
Pick the type first. A wallet-connect DEX widget suits a DeFi-literate audience. An instant exchange widget suits a general audience that holds coins on an exchange and just wants to move value.
Most of the pain people hit after embedding comes from a choice they skipped. Work through these criteria first.
Ask where user funds sit at every step. In a non-custodial design, the widget never holds user keys. The security notes of one open-source embed SDK treat the iframe as an independent security principal that the host does not read from. The LI.FI guide takes a similar approach: the parent page owns the wallet connection and the widget relays requests through it.
If a provider takes deposits and sends out funds later, that is a different business model with different compliance duties. Neither is wrong, but you should know which one you are putting on your domain.
A widget that supports ten coins is a feature. One that supports the coins your audience holds is a product. Check that stablecoins on the networks your users prefer are available, since the same stablecoin on different networks carries very different fees.
Every sign-up step costs conversions. Account-free flows are the fastest for the visitor, and they raise questions about compliance that we cover below. Our explainer on how no-KYC instant exchanges work lays out the mechanics.
Look for theme colors, default pairs, language, and the ability to preset a destination or a source asset. A widget that cannot match your typography will look like an ad, and visitors treat ads with suspicion when money is involved.
Some providers share revenue on swaps made through your embed. The SwapKit documentation points out that this is not automatic: an affiliate or partner identifier has to be configured in the widget settings during initial setup. If you embed first and monetize later, you may be sending volume that earns you nothing.
The exact parameters differ by provider, so treat this as the pattern and read your provider’s documentation for the specifics.
<iframe
src="https://widget.example.com/swap?from=btc&to=usdt"
title="Crypto swap"
width="100%"
height="640"
style="border:0;max-width:480px"
loading="lazy"
referrerpolicy="strict-origin-when-cross-origin"
></iframe>
sandbox attribute with only the permissions the widget needs. The MDN iframe reference warns that combining allow-scripts and allow-same-origin on a same-origin document lets it remove the sandbox, so do not grant both casually. Many third-party widgets need scripts to run at all, so test after you tighten.| Iframe | JavaScript SDK | |
|---|---|---|
| Setup time | Minutes | Hours to days |
| Styling control | Provider-defined options | Often deeper |
| Isolation from your page | Strong, by browser design | Depends on implementation |
| Wallet handling | Often inside the frame, or relayed by postMessage | Handled in your app |
| Best for | Content sites, landing pages, blogs | Apps, dashboards, custom UX |
For a marketing site or a blog, the iframe wins on speed and isolation. Reach for the SDK when the swap is a core product screen.
If your site runs on WordPress, you can skip hand-written HTML. We publish a white-label exchange widget plugin for WordPress and a production-ready exchange theme. The first adds a swap form to any page. The second is for sites where the exchange is the whole point.
An embedded widget runs code you did not write, next to pages your customers trust. Four habits cover most of the risk.
Validate message origins. If your page listens for postMessage events from the widget, check event.origin against the exact origin you expect. A write-up on cross-window communication misconfigurations shows how accepting messages from any source, or posting with a wildcard target, opens the door to cross-site scripting through a compromised third party.
const WIDGET_ORIGIN = new URL(iframe.src).origin;
window.addEventListener('message', (event) => {
if (event.origin !== WIDGET_ORIGIN) return;
// handle event.data
});
Deriving the origin from the iframe’s own source URL, as the LI.FI guide recommends, avoids typing it wrong and avoids wildcards.
Never pass keys. Wallet connection should be bridged by messages, with the host relaying signing requests. Private keys do not cross the frame boundary, ever. If a widget asks for a seed phrase, remove it.
Set frame-ancestors on your own pages. The same LI.FI guide advises a Content-Security-Policy with a frame-ancestors directive on the host to mitigate clickjacking. Note the direction: this controls who can frame your pages, which protects your logged-in areas, while the sandbox attribute and a frame-src rule control what you frame.
Limit what the frame can do. Use sandbox and a narrow allow list, and add the widget’s domain to your CSP frame-src so nothing else can load there.
Keep a short change log too: when you update the embed, note the date, the provider version and who approved it. If something goes wrong, you will want to know what changed.
This is the section people skip, so we put it before design.
A swap is a conversion between virtual assets. Businesses that facilitate exchange or transfer of virtual assets can fall under virtual asset service provider (VASP) rules. An AML guide to VASPs lists crypto-to-crypto exchange and transfers on behalf of a client among the covered activities, and notes that the FATF Travel Rule asks providers to collect and share originator and beneficiary data for qualifying transfers. As of mid-2025, that guide reports 73% of jurisdictions have enacted Travel Rule legislation, and enforcement timing still varies.
What that means for an embed depends on the setup:
We go deeper in our compliance playbook for crypto payments and in our piece on no-KYC swap APIs and noncustodial flows. Neither replaces legal advice, but both help you arrive at that conversation with the right questions.
We run a crypto payment gateway, and we also offer a KYC-free swap widget and API. That gives us a particular view of how people use embeds.
First, a swap widget works best where visitors already have a reason to hold or move crypto: a payments page, a wallet guide, a rates page, a gaming top-up flow. Dropping a swap form on an unrelated page gets looked at and ignored.
Second, the widget and the checkout should agree. A customer who lacks the right coin for your invoice should be able to convert in two clicks and come back. Merchants who treat swapping and accepting payments as separate projects tend to build the same friction twice.
Third, keep it simple. Choose a sensible default pair, state the fee and the estimated receive amount before anything is sent, and let people leave without an account. Most abandoned swaps we would expect to see come from surprises, not from technology.
Finally, be honest with your visitors about what you are. If you display someone else’s interface, say so in plain words near the widget and link to the terms of the service that runs it.
— Dustin
Put the widget near the content that creates the need. On a guide about buying a product with Bitcoin, place it after the explanation, not above the headline. A sticky link in the nav to a dedicated swap page also works.
Most swap forms are narrow, around 400 to 480 pixels. Center the frame, give it width:100% with a max width, and set a height that avoids an inner scrollbar on the confirmation step. Test on a small phone: the second screen of a swap flow is often taller than the first.
Preselect the pair your audience is most likely to want. A gaming community may default to a stablecoin into the game’s accepted coin. A freelancer-focused site may default to the major coins into a stablecoin.
Use loading="lazy" for frames below the fold, and avoid loading several widgets on one page. Third-party frames can slow your largest contentful paint if they sit above the fold.
Show the fee, the rate source and the time estimate. Add a short note on what happens if a swap is delayed, and a support contact. People move money only when they can see a way out.
A swap widget is the fastest option, but it is not the only one. If you want a fully custom screen, an API gives you price quotes and swap creation under your own design. Our walkthrough of the six steps from price to signed swap shows the flow, and the Exchange API documentation covers public, no-account swaps.
If visitors only need to compare values, a crypto converter with live prices or a live rates page may be all your content needs. A common pattern: converter on the guide, swap widget one click away on the same page.
If you want visitors to swap without an account, our instant crypto exchange works with no sign-up, and the widget and API let you bring that flow onto your own site. Teams that want their own branding can look at our white-label options, which are listed from 1% in fees.
If you also sell something, pair the swap with checkout. Our gateway accepts 110+ cryptocurrencies, including Bitcoin and Ethereum, through hosted checkout, plugins, payment links and API, with no KYC for merchants. Processing fees are published on our site in tiers tied to monthly volume, from 2% on Standard down to 0.1% on Enterprise, and there is a flat 0.10 $ per-payment option on the gateway page. Online stores can start with crypto payments for e-commerce.
sandbox, allow and CSP frame-src are set and tested.frame-ancestors policy.For a simple iframe, no. You paste a snippet into an HTML block or a page builder. A developer helps when you want origin checks, a CSP, custom events or an SDK integration inside an app.
It can be, if you choose a non-custodial provider and lock down the frame. Validate message origins, avoid wildcards, use sandbox and a frame-src rule, and never accept a widget that asks for private keys or seed phrases.
Only if the provider offers revenue sharing and you configure it. Documentation for at least one widget states that an affiliate ID must be set during setup, so check before launch and confirm how and when payouts happen.
It depends on your country and on who operates the swap. If the provider runs the regulated activity and you only display its interface, your duties are usually lighter, but adding your own fees, custody or instructions can change that. Ask a lawyer who handles crypto and money transmission in your jurisdiction.
Open a free CryptoPayr account and take your first crypto payment the same day.
Get started for free
Learn how to set crypto payment limits as a merchant: per-payment caps, daily totals, confirmation tiers and compliance triggers, with worked examples.
What a crypto payment receipt should contain, how to generate one, and which records a US business must keep for the IRS, with a ready-to-use field checklist.
Gas fees on Ethereum are far lower in 2026. Learn how timing, Layer 2s, gas settings and fee sponsorship cut what you or your customers pay.