Headless
Own form UI. The page holds the DPoP key and calls the gateway itself. The token galaxy is decoration: chains are solar systems, and a quote lights the route the API returned.
Customer effort
- Pro: full control of the look and feel, in any framework. No iframe and no postMessage.
- Con: the customer builds all the UI, and handles quote, approve and swap calls, API versions, and errors.
- Con: the customer owns the key and session code: key creation, proofs, refresh, and retries. @libs/widget-dpop covers this, but it then has to be published as a package for customers.
- Con: the event log shows proof-of-work difficulty, solve time, and pow_required or pow_wait retries. A 429 from the widget share or the per-session limit shows a Retry-After countdown.
Customer security
- Pro: no third-party iframe or script on the page. A copied token still fails elsewhere, because it is DPoP-bound and short-lived.
- Con: the DPoP key lives on the customer's origin. Any script on that page (an injected script, or a compromised third-party library) can use the key and session while the page is open, though it cannot export the key.
- Con: the customer's own Content Security Policy and dependency hygiene are the only line of defense.
Bridge
The same own-UI form. Every API call goes through a hidden iframe on the widget origin. The key never touches the page.
Customer effort
- Pro: own UI, with no crypto or session code. One connect() call, and our iframe handles refresh, retries, and API versions.
- Con: the session allowlist is quote, token search, Fusion and Fusion+ quotes, and token details. Address lookups, orderbook, balances, spot price, gas, charts, portfolio, history, and swap build are refused. New calls wait on us, and the API is asynchronous over postMessage.
- Con: one hidden iframe plus our loader script. Debugging crosses the iframe boundary.
- Con: the event log shows proof-of-work difficulty, solve time, and pow_required or pow_wait retries. A 429 from the widget share or the per-session limit shows a Retry-After countdown.
Customer security
- Pro: the key stays on the widget origin, and the token passes through the page but only works with that key.
- Pro: the allowlist limits what a compromised page can do. The iframe origin gate refuses a host whose origin is not on that list.
- Con: a compromised page can still call the allowed operations through the bridge while it is open. That spends quote quota. Address reads, orderbook lookups, spot price, gas, charts, portfolio, history, and swap builds are refused.
- Con: the customer trusts our loader and iframe. Their Content Security Policy must allow our script and frame origins.
Full widget
The hosted widget draws the swap UI. The page loads one script and calls mount().
Customer effort
- Pro: least work. One script, one mount() call, and theming through the Design Studio tokens.
- Pro: the snippet passes publishableKey and getSessionToken. The theme comes from the saved Design Studio config for that key, not from the snippet.
- Con: customization is limited to theme tokens and config. Layout is bounded by the iframe size.
- Con: when that config does not load, the page says the widget is using its built-in theme.
Customer security
- Pro: key, token, and UI all stay on our origin. The swap summary is rendered inside the iframe before the user signs, so a compromised host page cannot change what the user sees.
- Pro: the least customer code to get wrong.
- Con: the customer trusts our UI and loader. Wallet calls are relayed through the customer's wallet provider.
Widget without a backend
The same hosted widget. The page passes only the publishable key. When no-backend minting is on for that
key, the iframe mints by itself and does not call /session.
Customer effort
- Pro: no mint endpoint to run. One script, one mount() call, and a publishable key.
- Con: no-backend minting is off by default. Turn it on in Design Studio for this publishable key after saving an allowed origin.
- Con: this path is best-effort. 1inch can throttle it or turn it off. When the product flags are off, the embed says the widget is not available. A session that must stay available should mint with the secret key from your own backend.
Customer security
- Pro: the secret key never ships to the browser. The session's origins, lifetime, and scopes stay on the server.
- Con: the publishable key is public. Proof of work, the monthly widget share, and per-session limits are what hold a script back. The monthly share must stay below 100 percent while no-backend minting is on.
- Con: you still trust the loader and iframe, and a compromised page can ask the iframe to mint.