<iframe>. There is no @sodax/* package to install and
no backend to run: the widget carries its own SDK version and its own token list, so it picks up new
networks and assets without a release on your side.
Build your widget
Set the pair, restrict networks and tokens, brand it to match your product, and copy the embed —
with a live preview of the real widget beside you.
Before you start
The widget is a complete application, not a component you wire up. Knowing where the line falls saves you from looking for integration points that do not exist.The widget handles
Quoting, token and network lists, wallet connection, balances, approvals and allowance resets,
intent creation, signing, broadcast, settlement tracking, recovery after a reload, and the
receiving-account prerequisites some networks require.
Your page handles
A slot at least 760px tall, the
<iframe> and its allow attribute, a frame-src entry if you
run a Content Security Policy, and — optionally — a message listener for height and swap
status.- The frame owns its wallet session. Your user connects inside the widget. The React snippet
below wraps that same iframe — it is not a native component and it does not accept your app’s
wallet provider. If you want swaps on your own wallet connection, use
@sodax/dapp-kitinstead. - Quoting never needs a wallet. Visitors see live prices before connecting, so the widget is useful on a page where most people are logged out.
- Swaps are real and on mainnet. There is no test mode. The preview in the builder moves real funds, and the review dialog says so before anyone confirms.
Quickstart
1
Configure it
Open the builder, set your pair and restrictions, and brand it.
2
Copy the embed
The Integrate panel gives you HTML, a React component, or a prompt for your coding agent.
3
Paste it in
Drop it into your page, keeping the
allow attribute. Everything you configured travels in the
URL’s query string.What the widget can execute
Users can connect and sign in-widget for EVM, Solana, Sui, Stellar, NEAR, Stacks and Injective. Both sides of a route must be executable for the in-widget flow. The swaps API lists more networks than that. Those routes still quote in the widget, which then offers an explicit Continue on SODAX handoff rather than failing at signing time. Bitcoin is deliberately excluded from in-widget signing: it settles through a funded trading wallet, which is a different flow rather than another connector.Treat the executable list above as the coverage you advertise to your users, not the wider list the
token picker can quote.
Configure it in the builder
Three panels, with a live preview beside them that is a real iframe, not a mock.1
Setup
Choose the starting pair, amount and slippage, and restrict which networks and tokens each side
may use. Lock either side to its default token and network for a fixed corridor — a deposit-only
widget, say, or one that always sells your token.
2
Appearance
Set theme, accent, surface, font, radius and density. Text and button labels are derived from
your colours and contrast-checked, so a brand palette cannot produce a control nobody can read.
3
Integrate
Copy the embed as HTML or as a React component, or take the agent prompt and hand it to your
coding agent. A separate SDK example shows the same quote through
@sodax/sdk.Embed it
Both snippets are what the Integrate panel generates, already carrying whatever you configured — minus the panel’s inline comments, which this page covers in prose. The listener is optional; the<iframe> alone works.
frame-src:
Configuration parameters
Everything the builder sets is a query parameter on thesrc, so your page decides what the widget
opens on. Unknown values are discarded rather than guessed at.
A lock filters the side down to exactly the chain and token it was given, so it only does something
next to
embed=1 and a pair. On its own it matches nothing and the side lists no assets at all:
surface and theme together when hand-writing a URL. With surface alone the first paint uses
the visitor’s stored or system theme and then flips — the builder always writes both for you.
Swap lifecycle messages
The widget posts to your page’s origin, never*. Verify both event.origin and
event.source === frame.contentWindow in any listener, as the snippets above do.
Your page can send
{ type: 'sodax:theme', theme: 'light' | 'dark' | 'auto' } back after
sodax:ready to follow a theme toggle. Theme messages never connect a wallet or request a signature.
Earning on swaps
The widget can carry a partner fee, but it is deployment configuration rather than a URL parameter: the one field that redirects money is not something a page can set. That means your own deployment of the widget — get in touch and we will set it up with you.Troubleshooting
Next steps
Swap overview
How swaps are quoted and filled, and the other two ways to integrate them.
HTTP API
Build your own swap UI in any language — quote, intent, submit, poll.
React hooks
@sodax/dapp-kit when you want swaps native to your app, on your own wallet connection.Widget reference
Deployment variables, analytics events and the full lifecycle, in the repo.