Skip to main content
The SODAX swap widget puts a cross-network swap inside your product. Your users pick a pair, get a live quote, connect a wallet and sign — without leaving your page, and without you running any of it. SODAX routes the trade and independent solvers fill it, so there is no liquidity to bootstrap and no per-network deployment to maintain. It ships as a hosted page you put in an <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.
Three consequences worth reading before you paste anything:
  • 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-kit instead.
  • 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.
The preview is connected to mainnet. A swap you try in it moves real funds, and the review dialog says so before you confirm.

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.
Keep the allow attribute. Brave exposes wallet providers to a third-party frame only when the host page grants those features; other browsers ignore the names, so it costs you nothing to keep.
If your site sends a Content Security Policy, add the widget origin to frame-src:
Wallet availability inside frames varies by browser and extension, so the widget always keeps an Open in a new tab fallback for users whose wallet will not appear in an embedded context.

Configuration parameters

Everything the builder sets is a query parameter on the src, 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:
That URL fixes the user on Base USDC and leaves them free to pick anything on the destination side. The builder writes the pair for you whenever you tick a lock. Restrictions shape this UI, not access to the public API. A restriction that currently matches no listed asset permits no route, rather than substituting a different one — including a locked default token that is temporarily unavailable. Set 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.
Lifecycle messages carry a status and nothing else — no addresses, amounts, hashes or errors. They are UI notifications and delivery is best effort, so confirm settlement server-side before you credit an account, release an order or otherwise act on a payment.

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.