> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sodax.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> SODAX is mainnet-only (no testnet chains or RPC endpoints exist) with a hub-and-spoke architecture; Sonic is the hub. SODAX is non-custodial protocol/software: it routes and settles; independent solvers on the marketplace fill — never say 'our solver', 'the SODAX solver', that SODAX trades, takes custody, or fills orders. For frontend/React integrations, prefer @sodax/dapp-kit hooks over calling @sodax/sdk directly. SDK operations — the methods that build, submit or await a transaction, and the API/quote calls — return Result<T, E> ({ ok: true, value } or { ok: false, error }): check result.ok, never wrap them in try/catch or branch on error.message; discriminate on the narrow error.code union instead. Synchronous config getters (getPartnerFee, getSupportedSwapTokens, getVault, ...) return their value directly, not a Result.

# Swap widget

> Embed cross-network swaps in your product with one iframe. Create a free app ID, configure the widget visually, and paste the snippet into your page.

The SODAX swap widget puts cross-network swaps inside your product. Your users get a quote, connect
a wallet and swap without leaving your page.

* **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

**1. Create your app ID**

Sign in to the [SODAX dev portal](https://portal.sodax.com/widget?utm_source=sodax_widget\&utm_medium=widget_docs\&utm_campaign=widget_app_id)
for free, open **Swap widget**, set your fee and the Sonic address that receives it, and save.
That creates your app ID.

**2. Build your widget**

Open the [builder](https://widget.sodax.com), paste the ID into **Setup**, and set your pair,
restrictions and branding.

**3. Embed it**

Copy the HTML or React code from **Integrate** and paste it into your page.

## How it works

**Your app ID**

* 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](https://docs.sodax.com/developers/how-to/payout-wallet.md).

**What the widget handles**

* 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.

**What your page handles**

* 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.

**Wallets**

* 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`](https://docs.sodax.com/developers/packages/experience/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.

Advertise the first list to your users, not the wider one the token picker can quote.

## Configure it in the builder

The preview beside the panels is the real widget. It works before you add an app ID, without your
fee, and swaps in it use real funds.

* **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

> [!WARNING]
>
> Create your app ID in the [SODAX dev portal](https://portal.sodax.com/widget?utm_source=sodax_widget\&utm_medium=widget_docs\&utm_campaign=widget_app_id)
> first. Left as `YOUR_APP_ID`, the widget does not quote or swap.

The whole embed is one `<iframe>`:

```html theme={null}
<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>
```

**Integrate** gives you this with your app ID and settings filled in, plus an optional listener for
height and swap status, as HTML or a React component.

* **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`:

```http theme={null}
Content-Security-Policy: frame-src https://widget.sodax.com;
```

## Configuration parameters

The builder writes these into the `src` for you. Unknown values are ignored.

| Parameter | Value |
| - | - |
| `appId` | Required. From the dev portal's **Swap widget** tab |
| `embed` | `1` shows the widget without the builder |
| `srcChain`, `dstChain` | Chain keys |
| `srcToken`, `dstToken` | Token symbols on the chosen chain |
| `amount`, `slippage` | Decimal amount and slippage percentage |
| `allowedSrc`, `allowedDst` | Comma-separated chain keys. Absent or empty allows every network |
| `allowedSrcTokens`, `allowedDstTokens` | Comma-separated `chainKey:symbol`. Absent allows all; present but empty allows none |
| `lockSrc`, `lockDst` | `1` pins that side to the chain and token in the URL |
| `theme` | `light`, `dark` or `auto` |
| `accent`, `cta`, `surface`, `text` | Six-digit hex without `#`. `cta` is the button colour |
| `radius`, `font`, `density` | The named options in **Appearance** |

* **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.

This URL fixes the source to Base USDC and leaves the destination open:

```
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.

| Message | Meaning |
| - | - |
| `sodax:ready` | Widget mounted. Assets and wallets may still be loading |
| `sodax:resize` | Content height. Clamp it to 760–1600px |
| `sodax:swap` `started` | User confirmed the review |
| `sodax:swap` `submitted` | Deposit broadcast. Settlement pending |
| `sodax:swap` `completed` | Swap settled |
| `sodax:swap` `failed` | Failed before broadcast, failed to settle, or the user stopped waiting on a wallet that never confirmed. In that last case the deposit can still land |

To follow your site's theme, send `{ type: 'sodax:theme', theme: 'light' | 'dark' | 'auto' }` after
`sodax:ready`.

> [!WARNING]
>
> These are best-effort UI notifications with nothing you could verify a swap against. Do not credit
> an account, release an order or act on a payment because of one.

## Troubleshooting

| Symptom | Fix |
| - | - |
| Widget asks for an app ID, or says yours is not valid or unknown | Add `appId` to the embed URL, copied exactly from the dev portal's **Swap widget** tab |
| **Copy** in the builder opens Setup | Paste your app ID into **Setup** first |
| Wallet does not appear in the frame | Keep `allow="ethereum; solana; clipboard-write"` on the `<iframe>`. Users can also use **Open in a new tab** |
| Widget does not load | Add `https://widget.sodax.com` to your Content Security Policy's `frame-src` |
| Content is clipped or scrolls inside the frame | Reserve at least 760px and add the listener from **Integrate**, which resizes the frame |
| Theme flashes on first paint | Set `theme` alongside `surface` |
| A colour renders differently | Use six-digit hex without `#`. Text colours are adjusted for contrast |
| No `message` events reach your page | Check `event.origin` and `event.source`, and keep `referrerpolicy="origin"` |
| A pair quotes but cannot be signed | The route is [quote only](#what-the-widget-can-execute). Users get **Continue on SODAX** |
| A restricted token never appears | An empty allowlist allows nothing, and a `chainKey:symbol` that matches no listed asset blocks the route |

## Next steps

> [card] [Swap overview](https://docs.sodax.com/swap.md)
>
> How swaps work, and the other ways to integrate them.

> [card] [HTTP API](https://docs.sodax.com/developers/http-api/swaps.md)
>
> Your own swap UI, in any language.

> [card] [React hooks](https://docs.sodax.com/developers/packages/experience/dapp-kit.md)
>
> `@sodax/dapp-kit`, for swaps on your own wallet connection.

> [card] [Widget reference](https://github.com/gosodax/sodax-sdks/blob/main/apps/playground/README.md)
>
> The full lifecycle and analytics events, in the repo.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.