Swap widget

• One iframe, nothing to run. No @sodax/* package, no backend, no liquidity to bootstrap. New networks and assets appear without a release on your side.
• Your fee. Set it from 0 to 1% in the dev portal, behind your app ID.
• Real swaps. Mainnet only, with no test mode. That includes the preview in the builder.

​

Quickstart

​

How it works

• Required: without it, the widget does not quote or swap.
• It holds your fee and its receiving address, so nobody can change them by editing the embed.
• It is public and never changes, so it is safe in your page’s source.
• It covers widget swaps only, not swaps you make through the SDK or API.
• Fees build up on Sonic until you claim them.

• Quotes, network and token lists, wallet connection, balances and approvals.
• Signing, settlement tracking and recovery after a page reload.
• Receiving-account setup that some networks require.

• The <iframe> with its allow attribute, in a slot at least 760px tall.
• A frame-src entry, if you send a Content Security Policy.
• Optionally, a message listener for height and swap status.

• Users connect their wallet inside the widget, not through your app. The React snippet wraps the same iframe. To swap on your own wallet connection, use @sodax/dapp-kit instead.
• Quotes show before a wallet is connected.

​

What the widget can execute

• Swap in the widget: EVM, Solana, Sui, Stellar, NEAR, Stacks and Injective. Both sides of the route must be on this list.
• Quote only: every other network the swaps API lists. Users see the quote, then Continue on SODAX opens the SODAX exchange, where they select the trade again. The builder and token picker label these networks Quote only.
• Bitcoin never signs in the widget: it settles through a funded trading wallet.

​

Configure it in the builder

• Setup: your app ID, the starting pair, amount and slippage, and which networks and tokens each side allows. Lock a side to fix its token and network, for example for a deposit-only widget.
• Appearance: a preset, or your own theme, colours, font, radius and density. Text that would be hard to read is adjusted for contrast.
• Integrate: your code as HTML, React or a prompt for your coding agent, once your app ID is in. The SDK tab shows the same quote with @sodax/dapp-kit.

​

Embed it

<iframe
  src="https://widget.sodax.com/?embed=1&appId=YOUR_APP_ID"
  title="SODAX swap"
  width="480"
  height="760"
  loading="lazy"
  referrerpolicy="origin"
  allow="ethereum; solana; clipboard-write"
  style="border: 0; border-radius: 24px; max-width: 100%"
></iframe>

• Keep the allow attribute. Brave shows wallets to a third-party frame only when the host page allows it. Other browsers ignore it.
• No wallet in the frame? The widget always offers users Open in a new tab.
• Content Security Policy? Add the widget to frame-src:

Content-Security-Policy: frame-src https://widget.sodax.com;

​

Configuration parameters

• Locks need embed=1 and the pair they pin. Without the pair, that side lists no assets.
• Restrictions shape this UI, not access to the public API. One that matches no listed asset blocks the route rather than swapping in another token, even when a locked token is only temporarily unavailable.
• Hand-writing a URL? Set theme with surface, or the first paint can flip themes.

https://widget.sodax.com/?embed=1&appId=YOUR_APP_ID&srcChain=0x2105.base&srcToken=USDC&lockSrc=1&dstChain=solana

​

Swap lifecycle messages

• The widget posts only to your page’s origin, never *. Check event.origin and event.source in your listener, as the one from Integrate does.
• Messages carry a status and nothing else: no addresses, amounts or hashes.

​

Troubleshooting

​

Next steps